@ahmed-g-gad/apothem 0.1.1

package/src/apothem/rules/README.md

@@ -0,0 +1,121 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rules
+
+Behavioral instruction rules — flat `.md` files, each a self-contained directive set the harness loads to govern agent behavior. Each carries YAML frontmatter declaring `name`, `description`, `pathFilter`, and `alwaysApply`; a body of obligations; and a `## Bindings` section wiring it to its peers.
+
+## Always-on vs path-filtered rules
+
+Every rule is one of two kinds, declared in frontmatter:
+
+- **Always-on** — `alwaysApply: true` with an empty `pathFilter:`. Loaded into every session. To keep the always-on tier lean, each always-on body is capped at 500 substantive tokens per `token-budget-discipline.md`.
+- **Path-filtered (companion)** — `alwaysApply: false` with a `pathFilter:` glob list. Demand-loaded only when the agent touches a matching artifact.
+
+## The parent / companion-sub-rule pattern
+
+When an always-on rule's content exceeds the token ceiling, it decomposes along a path-filtered seam: the **parent** rule retains the standing directive plus a one-line summary and a `(Companion Sub-Rule Anchor)` pointer; the **companion** sibling — named `<parent>-<aspect>.md`, path-filtered — carries the operational depth (catalogs, worked examples, executable matchers, full tables). The companion demand-loads only when relevant, so detail pays its context cost only where it applies. Pairs are reciprocally cited in each rule's `## Bindings` block.
+
+## The `## Bindings` five-direction section
+
+Every rule closes with a `## Bindings (§0.j five-direction)` section declaring its place in the rule graph along five reciprocal directions: **Drives →** (what it causes), **Driven by ← / Established by ↑** (what gates / ratifies it), **Satisfies →** (what end-state it meets), and **Cross-bound with ↔** (sibling rules that mutually reinforce). Every declared binding has a reciprocal back-pointer at the other end; the discipline is specified in `bidirectional-binding.md`.
+
+## Rule families
+
+### Cognitive identity & generation methodology
+
+| Rule | Concern |
+|------|---------|
+| `cognitive-identity.md` · `cognitive-identity-techniques.md` | The cognitive-insurgent identity — five creative filters, six ideation techniques, language standards, seven-axs-of-breadth taxonomy. |
+| `clean-room-generation.md` · `clean-room-generation-protocols.md` | Specification-derived original output — Writing / Re-Writing protocols, code-generation discipline. |
+| `planning-techniques.md` | Nine planning review techniques for plan generation, review, execution. |
+
+### Operational mandates & quality gates
+
+| Rule | Concern |
+|------|---------|
+| `agnostic-posture.md` · `agnostic-posture-checklist.md` | Default-off, opt-in posture for every shipped behavior; correctness gates stay advisory; harness-neutral surfaces; model / effort / workflow preference is end-user-invoked — plus the per-invariant verification checklist every phase's definition of done satisfies. |
+| `agents-md-convention.md` | The root `AGENTS.md` is the single agent-facing canon; per-folder operating guidance lives in each folder's `README.md` (one file, both the human and agent reader); per-folder `AGENTS.md` companions are not required, and any present companion stays current and canon-coherent with the root AI-surface canon. |
+| `operational-mandates.md` · `operational-mandates-expanded.md` | Operational mandates CM-1–CM-10 — critical evaluation, zero assumptions, search-before-implement, brutal honesty. |
+| `pre-emission-gate.md` · `pre-emission-gate-bars.md` | The fifteen-bar pre-emission gate (M1–M15) every artifact passes before emission, with a recorded attestation. |
+| `ten-dimension-check.md` · `ten-dimension-check-dimensions.md` | The ten quality dimensions applied to every artifact (M3). |
+| `definitiveness.md` · `definitiveness-virtues.md` | Definitive, airtight statements; hedging elimination; the rigorous-systems virtues (M8). |
+| `etc-extension.md` | Enumerations are seeds, not ceilings — every open-set marker (`etc.` / `e.g.` / `such as` / `like` / `including` / `…`) is a directive to extend comprehensively from intent; an explicitly-closed enumeration is exempt. |
+| `source-accessibility.md` | Source trust outranks accessibility — reach a trusted-but-inaccessible source via browser then operator interview; never prefer untrusted-but-free over trusted-but-inaccessible; record the source-trust decision. |
+| `authoritative-referencing.md` · `authoritative-referencing-quotation.md` | Every claim / argument / hypothesis / fact cites an authoritative, official, current source — the scattered dim-9 / sota named-exemplar / disclosure-ledger / output-style-citation discipline consolidated by reference; folklore and "industry standard" appeals are non-conformant. The path-filtered companion binds the reproduction form: paraphrase by default with attribution, quote sparingly and briefly, never reproduce a full third-party work, attribute without a legal opinion. |
+| `dynamism.md` | No static substitutions for dynamic-source-of-truth values — version / badge / release / docs-version / runtime `__version__` / social-card stamps render from one live authority; the `static-version-grep` matcher enforces the closed surface set. |
+| `sota-elevation.md` · `sota-elevation-exemplars.md` | State-of-the-art elevation as the default posture for OSS-distribution surfaces — eight SOTA evaluation surfaces, named-exemplar discipline, MAXIMAL upper-bound calibration. |
+
+### Host-project conduct (the M-mandate family)
+
+| Rule | Concern |
+|------|---------|
+| `host-discovery.md` · `host-discovery-manifests.md` | Discover and honor host-project conventions before emitting (M1). |
+| `disclosure-ledger.md` · `disclosure-ledger-markers.md` | Disclosed amendments, never silent — the change ledger (M2). |
+| `authority-inquiry.md` · `authority-inquiry-categories.md` | Inquire, do not invent — names, endpoints, scope, version pins (M5). |
+| `expertise-posture.md` · `expertise-posture-elements.md` | Read intent, amend proactively, surface gaps (M6). |
+| `option-annotation.md` · `option-annotation-form.md` | Every multi-option choice carries a Recommended marker plus rationale (M7). |
+| `visual-leverage.md` | Diagrams where structure is the subject (M9). |
+| `bidirectional-binding.md` | Reciprocal five-direction bindings; phase-execution threading (M10). |
+| `agile-sprints.md` · `agile-sprints-elements.md` | Non-trivial multi-step work runs as disciplined Agile sprints (M11). |
+| `canonical-layout.md` · `canonical-layout-reporting-tiers.md` | Two-tier phase reporting; canonical output layout; orphan prevention (M12). |
+| `systemic-participation.md` · `systemic-participation-relations.md` | Artifacts join the host as systemic participants — no orphans, no silos (M14). |
+| `production-ready-prs.md` · `production-ready-prs-surfaces.md` | Every change ships production-ready — tests, docs, CHANGELOG, CI green (M15). |
+| `own-voice-reimplementation.md` | Reference-derived features reauthored in apothem's own voice — zero verbatim copy, mandatory elevation, harness-doc-aligned. |
+| `living-docs.md` | Every change to a documented public surface updates its docs page in the same change-set — the documentation analogue of the production-ready discipline; CI's docs-reference-sync drift gate enforces it. |
+| `freshness-facade.md` | Shipped public surfaces stay a current-version-only facade — no AI-disclosure, backward / legacy / placeholder, or fix-and-refinement narrative; the `freshness-token-grep` matcher gives the closed token-class list mechanical teeth on README plus site copy. |
+| `surgical-manipulation.md` | Surgical, anchor-bounded, minimal-diff mutation discipline — scoped edits over blunt whole-file overwrites across every file class; paired with the `surgical-guard` skill's post-edit quality pass. |
+| `propagation.md` | Full-reference-graph propagation — every mutation propagates same-change-set across code / docs / tests / examples / registries / plugins / bindings; generalizes `living-docs.md` + `systemic-participation.md` and binds the existing drift gates (the CM-8 keystone). |
+| `refactoring-discipline.md` | Agent-driven refactoring is test-gated (green before AND after), one concern at a time, plan-first, and continuous — the workflow / cadence discipline that gates the clean-room re-writing protocol for a refactor. |
+| `harness-adapter-shape.md` · `harness-adapter-shape-schemas.md` | Every adapter in the 17-harness cohort performs host discovery, converges on the sibling adapter shape, declares divergences, carries the adapter-test matrix, and ships a co-resident STANDARD-CONVENTION-PIN. |
+| `i18n-discipline.md` · `i18n-discipline-locale-cohorts.md` | Translated surfaces ship in every Modern-Dev-Cohort locale or surface the gap — framework i18n integration, machine-seed + human-review gate, per-locale glossary, RTL + hreflang discipline. |
+| `plain-language.md` | User-facing narrative free of process-tooling leak — AI / harness / plan-stage / process vocabulary stays out of README / docs / site copy; the `plain-language-grep` matcher enforces the closed set with domain carve-outs. |
+
+### Code craft (M13, per language)
+
+| Rule | Concern |
+|------|---------|
+| `code-craft-conventions.md` | Universal code-craft delegation stub for languages without a dedicated rule. |
+| `code-craft-python.md` | Python — SOLID, modern type hints, Google-style docstrings, pytest, security guardrails. |
+| `code-craft-shell.md` | Shell — POSIX bash + PowerShell idioms, strict mode, injection prevention. |
+| `code-craft-markdown.md` | Markdown / prose — purpose-driven structure, sentence-level justification, active voice. |
+| `clean-architecture-layers.md` | Domain / Application / Infrastructure / Presentation layer discipline. |
+
+### Context, memory & conventions
+
+| Rule | Concern |
+|------|---------|
+| `context-management.md` · `context-management-protocol.md` · `context-management-scratch.md` · `context-management-budget.md` | Context-rot mitigation, blind-execution protocol, externalization, plan-workflow scratch convention, per-task effort calibration + context-budget discipline. |
+| `auto-memory.md` · `auto-memory-topic-files.md` | Auto-memory lifecycle — topic files, MEMORY.md index, promotion ledger. |
+| `persistent-conventions-vigilance.md` · `persistent-conventions-vigilance-checklist.md` | Ecosystem-convention adherence and proactive artifact evolution (CM-22). |
+| `large-file-generation.md` | Large file generation via incremental appends (CM-23). |
+| `token-budget-discipline.md` | The 500-token ceiling on always-on rule bodies. |
+| `large-file-reading.md` | Size-aware file reading — pre-read assessment, locate-before-read, structural traversal, segmentation; the read-side analogue of `large-file-generation.md`. |
+| `token-efficiency-rewrite.md` · `token-efficiency-rewrite-protocol.md` | Token-efficiency as a rewrite discipline — preserve L2 semantic content + L3 structural anchors, discard L1 scaffolding; pairs with `token-budget-discipline.md` (caps) to fit the always-on ceiling. |
+
+### Agent orchestration & interaction
+
+| Rule | Concern |
+|------|---------|
+| `agent-orchestration.md` · `agent-orchestration-patterns.md` | Agent / agent-team deployment patterns, return contracts, context isolation. |
+| `agent-capability-discipline.md` · `agent-capability-discipline-matrix.md` | Per-harness agentic-capability matrix across the 17-harness cohort — MCP support, sub-agent dispatch, tool-surface restriction, agent-memory convention, output-style / custom-command / hooks / skills surfaces. |
+| `multi-agent-workflow.md` | Independent-critique / open-loop / dynamic multi-agent execution as an available, specified capability — opt-in and default-off under the agnostic posture; orchestration mechanics owned by `agent-orchestration.md`. |
+| `tool-use-discipline.md` | Ordinary tool use as a disciplined loop — independent calls batched in one turn (the ordinary-tool-tier generalization of the agent-tier single-message parallel-launch), the observe → decide → act cadence named, and iteration to a verifiable exit rather than a fixed count. |
+| `interactive-questions.md` · `interactive-questions-canonical-shapes.md` · `interactive-questions-sweep-matchers.md` · `interactive-questions-detail.md` | The structured-inquiry channel — Structured-Inquiry Shape, option annotation, sweep matchers, authoring discipline + anti-patterns. |
+| `determinism.md` · `recommend-next-step.md` | Deterministic output shape across command and skill surfaces; the `(Recommended)`-in-header invariant; every terminal surface closes with a definitive named next step. |
+| `session-closure.md` | Every session — ad-hoc conversational sessions included, not only plan phases — ends with a formal, verifiable close: a terminal Recommended Next Step, a done/deferred ledger, and a verification attestation; harness-agnostic. |
+| `performance-discipline.md` | Per-class performance budgets and quantitative gates. |
+
+## Conventions
+
+- One flat `.md` file per rule; kebab-case filenames; companion files suffix the parent name with the aspect.
+- Every file carries the canonical single-line SPDX license header and a non-empty `description` frontmatter field.
+- Cross-references between rules use relative paths and are reciprocal in the `## Bindings` section.
+
+## Operating in this folder
+
+- **File shape.** YAML frontmatter (`name`, `description`, `pathFilter`, `alwaysApply`) → the single-line SPDX license header (HTML-comment form) → the obligations body → a closing `## Bindings (§0.j five-direction)` section. The frontmatter `description` field MUST be populated; the PreToolUse frontmatter check rejects an empty one.
+- **Token budget.** An always-on body (`alwaysApply: true`, empty `pathFilter`) is capped at 500 substantive tokens per `token-budget-discipline.md`; over-budget content decomposes into a path-filtered companion rather than inflating the parent.
+- **Reciprocal bindings.** Every `## Bindings` cross-reference has a matching back-pointer at the cited peer; half-edges fail the bindings-reciprocity gate.
+- **Harness-neutral prose.** This folder is swept by the agnosticism and reference-token matchers. Name a harness only by its catalog slug — one entry among the registered set — never by a privileging brand phrase, and pre-set no model or effort preference.
+- **Adding a rule:** author the file with the shape above, add its row to the registry table above, and wire it into the rule graph via its `## Bindings` section; decide always-on vs companion by the token budget. **Splitting an over-budget always-on rule:** move depth to a `<parent>-<aspect>.md` companion, leave the `(Companion Sub-Rule Anchor)` pointer in the parent, and make both `## Bindings` blocks cite each other.
+- Validate every change with `python -m apothem.conformity.gate --all .` (frontmatter, token-budget, bindings-reciprocity, agnosticism, reference-token matchers) and `python -m pytest`.

package/src/apothem/rules/agent-capability-discipline-matrix.md

@@ -0,0 +1,89 @@
+---
+name: "agent-capability-discipline-matrix"
+description: "Path-filtered companion to `agent-capability-discipline.md` — carries the per-harness agentic-capability matrix (§1), the per-harness MCP-surface catalog (§3), and the per-harness agent-memory-convention catalog (§7) the parent rule's anchors delegate to. Demand-loaded when the assistant edits any adapter sub-package, cross-harness capability-matrix input, or per-harness MCP-config artifact."
+pathFilter: "**/src/apothem/harnesses/**, **/_inputs/cross-harness-agent-capability-matrix.md, **/.mcp.json, **/mcp.json"
+alwaysApply: false
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Agent Capability Discipline — Per-Harness Matrix (Companion Sub-Rule)
+
+## Purpose
+
+Carry the per-harness agentic-capability matrix, the per-harness MCP-surface catalog, and the per-harness agent-memory-convention catalog that the parent `rules/agent-capability-discipline.md` rule's §1 / §3 / §7 anchors delegate to. Path-filtered: loads when the assistant edits adapter sub-packages under `src/apothem/harnesses/<name>/`, the cross-harness capability-matrix scratch input under `_inputs/cross-harness-agent-capability-matrix.md`, or per-harness MCP-config artifacts (`.mcp.json`, `mcp.json`). The parent rule retains the standing directive, the plain-language boundary, the disclosure surface, the failure tells, and the bindings; this companion carries the per-harness operational catalogs.
+
+## Obligations
+
+### 1. Per-Harness Agentic-Capability Matrix
+
+Every cell is one of: **yes** (vendor-supported per the adapter's pinned snapshot), **no** (vendor does not support), **partial** (vendor supports a subset; the adapter's STANDARD CONVENTION PIN names the subset boundary), **discovery-pending** (the capability has not yet been discovered against the harness's pinned snapshot; surfaces as a finding per the disclosure ledger).
+
+The matrix axes:
+
+- **Rows (17 harnesses):** antigravity, claude_code, codebuddy, codex, cursor, gemini_cli, github_copilot, hermes, kimi_code, kiro, open_claw, opencode, qwen_code, trae, windsurf, zed, glm.
+- **Core columns (9 capabilities):** MCP server support · sub-agent dispatch · tool-surface restrictions · system-prompt template surface · agent-memory convention · output-style support · custom-command support · hooks-pipeline support · skills-directory support.
+- **Supplemental operational columns:** recommended-postfix rendering · long-context/compaction continuity · context-ignore surface · layered-context surface · LSP/symbol-navigation surface · hook-learning capture surface · standard-convention pin pointer · web-fetch / browser-retrieval surface (the `web_fetch` projection backing `rules/source-accessibility.md` step 1's "retrieve through the host's browser / fetch capability" escalation).
+
+Each row's authoritative cell values live co-resident with the adapter's STANDARD CONVENTION PIN at `src/apothem/harnesses/<name>/STANDARD-CONVENTION-PIN.md` per `rules/harness-adapter-shape.md` §6. Until every adapter pin carries the full evidence chain, `src/apothem/harnesses/<name>/capabilities.yml` is the interim machine-readable projection for installed checks; it carries the legacy five required fields plus `custom_command_support`, `recommended_postfix_rendering`, `long_context_compaction`, `context_ignore_surface`, `layered_context_surface`, `lsp_symbol_navigation`, `hook_learning_capture`, `standard_convention_pin`, and `web_fetch` (the web-fetch / browser-retrieval surface per §1A). The aggregate cross-harness matrix is materialized at `_inputs/cross-harness-agent-capability-matrix.md` during the cross-harness convergence walks.
+
+Per-cell evidence requirement: every **yes** / **partial** cell MUST cite the vendor-doc-url + commit-sha + snapshot-date triple from the adapter's pin. Every **no** cell cites the same triple plus a one-sentence rationale naming the vendor surface that lacks the capability. Every **discovery-pending** cell carries an inquiry-id per `rules/authority-inquiry.md` so the gap is tracked.
+
+Per-row attestation surface: the adapter's gate-attestation block per `rules/pre-emission-gate.md` carries an `agent-capability-coverage: <yes | partial | no | discovery-pending>` field per column, mirrored from the matrix row.
+
+Matrix-staleness check: a cell whose snapshot-date is older than 90 days against current vendor reality surfaces as a finding per `rules/harness-adapter-shape.md` §6 stale-pin discipline. The companion's evidence chain is the parent rule's STANDARD CONVENTION PIN evidence chain — never duplicated, always referenced.
+
+### 1A. Web-Fetch / Browser-Retrieval Surface — the M2 Source-Accessibility Backing Dimension
+
+The `web_fetch` supplemental column is the per-harness declaration of whether the harness exposes a vendor-native web-fetch / URL-retrieval / web-search / browser tool. It is the real backing dimension for `rules/source-accessibility.md` step 1's escalation — "retrieve it directly through the host's browser / fetch capability" — so the escalation reads a declared cell instead of assuming a capability. Each harness's `capabilities.yml` carries the `web_fetch` field as one of: **yes** / **no** / **partial** / **discovery-pending**, with the same per-cell evidence requirement as §1: a **yes** / **partial** cell cites the vendor-doc-url + commit-sha + snapshot-date triple from the adapter's pin; a **no** cell cites the triple plus a rationale; a **discovery-pending** cell carries the tracked-gap note. When a harness's `web_fetch` cell is **no** or **discovery-pending**, `rules/source-accessibility.md` step 2 (operator-interview escalation per `rules/authority-inquiry.md`) is the live path — the absence of a fetch capability does not abandon the trusted source, it routes the retrieval to the operator.
+
+Current sweep state (web-fetch evidence pass, snapshot-date 2026-06-21): eight harnesses are vendor-confirmed and now carry an inline evidence triple (vendor-doc-url + snapshot-id + snapshot-date) in their `capabilities.yml` `web_fetch` comment block — **yes**: `claude_code` (built-in WebFetch + WebSearch), `gemini_cli` (built-in `web_fetch` + `google_web_search`, commit-pinned to the adapter's own immutable snapshot), `codex` (first-party web search tool, default-on for local tasks), `github_copilot` (Copilot CLI `web_fetch` tool, URL-permission-gated), `windsurf` (Cascade Web Search + URL Read, admin-toggle-gated); **partial**: `qwen_code` (built-in `web_fetch` yes, `web_search` removed → MCP-only), `opencode` (`webfetch` unconditional, `websearch` provider/env-gated), `cursor` (`@Web` user-invoked context search, no documented autonomous fetch tool). The remaining seven — `antigravity`, `codebuddy`, `hermes`, `kiro`, `open_claw`, `trae`, `zed` — stay **discovery-pending**: no authoritative vendor source was located in this sweep, and the §1 definition forbids asserting `no` (vendor lacks it) or `yes` (without the triple) absent evidence. The eight populated cells' canonical evidence home remains the STANDARD CONVENTION PIN per §1's per-cell requirement; the inline `capabilities.yml` triple is the interim machine-readable carrier until a pin refresh folds each triple into the adapter's pin "Native Surfaces" block (the open follow-up). The 15 STANDARD CONVENTION PINs were last pinned (2026-05-31) cataloging config-materialization surfaces (rules files, MCP registration surfaces, hooks, skills, commands, memory), not the vendor runtime tool catalog — the pin-refresh follow-up adds the web-fetch tool row to each populated harness's pin.
+
+### 1B. Per-Harness "(Recommended)"-Annotation Enforcement Gap (M5)
+
+The `(Recommended)` option-label postfix is specified behaviorally at `rules/determinism.md` §1, `rules/option-annotation.md` / `rules/option-annotation-form.md`, and `rules/interactive-questions-canonical-shapes.md` §2.1. The **runtime well-formedness guard** for that postfix is `hooks/askuserquestion_validator.py`, which fires on the `AskUserQuestion` tool event and checks the rendered option set's recommended-marker placement and bidirectional bind at call time. That guard is wired into exactly **one** harness:
+
+- **claude_code** — the validator is registered in the generated `templates/settings.json` (matcher `AskUserQuestion` → the `pretooluse-askuserquestion-recommended` hook message). claude_code is the **only** harness whose operators get a call-time guard on the `(Recommended)` rendering.
+- **The other 14 harnesses** (antigravity, codebuddy, codex, cursor, gemini_cli, github_copilot, hermes, kiro, open_claw, opencode, qwen_code, trae, windsurf, zed) receive the `(Recommended)` discipline as **behavioral rules text only** — the rule prose is materialized into each harness's instruction surface, but no call-time validator inspects the rendered option set. The enforcement floor for these 14 is the pre-emission conformity sweep on authored artifacts (`conformity/option_annotation_grep.py`, `conformity/determinism_grep.py`), not a runtime call-time guard.
+
+**Wiring candidates.** Among the 14 text-only harnesses, **codex** (`~/.codex/hooks.json` hook surface) and **qwen_code** (`settings.json` hooks namespace) are the hook-capable candidates for wiring the same `AskUserQuestion`-equivalent validator, since both ratify a hooks-pipeline surface in their pins (codex `hooks.json`; qwen_code `hook_learning_capture: settings.json-hooks`). gemini_cli also documents a native settings.json hooks surface but the adapter keeps hook prose as support material and registers no native hooks (see its `capabilities.yml`), so it is a secondary candidate behind codex and qwen_code. Wiring those two would close the runtime-enforcement gap for the harnesses that can host a call-time guard; the remaining rules-only harnesses stay on the authored-artifact conformity floor. This is a tracked divergence, not a defect — the `(Recommended)` discipline is materialized everywhere; only the call-time guard is claude_code-exclusive today.
+
+### 3. Per-Harness MCP-Surface Catalog
+
+Per-harness MCP server registration surfaces, projected from the shared profile's canonical MCP inventory:
+
+- **claude_code** — `mcpServers` block inside `~/.claude/settings.json` (user-scope) plus project-level `.mcp.json` (project-scope). The adapter's materializer renders both surfaces from the profile's MCP inventory.
+- **cursor** — `~/.cursor/mcp.json` (user-scope) plus project-level `.cursor/mcp.json` analogue where the vendor supports per-project MCP scoping.
+- **codex / opencode / open_claw / qwen_code / antigravity / hermes / gemini_cli / windsurf / github_copilot** — per-harness MCP surface declared at the adapter's STANDARD CONVENTION PIN under `canonical-filename:` and `canonical-schema:` fields per `rules/harness-adapter-shape.md` §6. Where the harness does not yet expose an MCP surface (matrix column 1 cell is **no** or **discovery-pending**), the adapter declares the absence and the profile's MCP inventory is materialized into a sibling fallback surface (e.g., a system-prompt-embedded MCP descriptor) where the vendor surface permits, or omitted with an explicit `[Refusal — …]` ledger row per the parent rule's disclosure surface.
+
+Sharing discipline: the profile's MCP inventory is the single source of truth; a per-harness surface MUST NOT silently diverge from the inventory. Operator-authored per-harness override rows (a harness-specific MCP server the operator declares for one harness only) are recorded explicitly in the profile's `mcp.overrides.<harness>` block and carry a concrete-driver rationale per `rules/interactive-questions-canonical-shapes.md` §3.2.1.
+
+Project-vs-user scoping: the profile's MCP entries declare scope (`user` / `project` / `both`) and the per-harness materializer projects the scope into the harness's ratified surface (claude_code's project-level `.mcp.json` vs. user-level `mcpServers` block; cursor's project-level `.cursor/mcp.json` vs. user-level `~/.cursor/mcp.json`; per-harness analogues).
+
+Discovery-pending MCP surfaces: when a harness's pinned snapshot does not yet document an MCP surface, the adapter carries a `mcp-surface: discovery-pending` field in its STANDARD CONVENTION PIN until the vendor surface ratifies; the materializer refuses MCP materialization for that harness per the parent rule's §8 refusal-and-override flow.
+
+### 7. Per-Harness Agent-Memory-Convention Catalog
+
+Per-harness agent-memory persistence semantics:
+
+- **persists-across-sessions** — the harness's memory surface survives session boundaries (vendor-ratified durable memory; e.g., a `memory/` directory or a memory-store file the harness reads at session start). The adapter's materializer emits the cohort's shared memory content into the harness's ratified durable surface.
+- **does-not-persist** — the harness has no durable memory surface; agent memory is session-local. The adapter declares the absence and the profile's memory content is projected into the harness's system-prompt template surface (parent rule §6) as a read-only memory snapshot at session start where the vendor surface permits, or omitted with an explicit ledger row.
+- **migrates** — the harness's memory surface admits import from an adjacent harness's memory format (vendor-ratified memory portability). The adapter declares the migration source-and-target pair, the migration script (under `src/apothem/harnesses/<name>/memory_migration.py` or equivalent), and the migration's idempotency guarantees.
+
+The per-harness memory-convention cell maps to matrix column 5 (agent-memory convention) of §1. The adapter's STANDARD CONVENTION PIN carries the memory-convention field under `agent-memory: persists-across-sessions | does-not-persist | migrates` with per-harness specifics (the durable surface's path, the migration source-and-target pair, the read-only-snapshot projection surface).
+
+Cross-harness memory portability table: the aggregate per-harness memory-convention map lives at `_inputs/cross-harness-agent-capability-matrix.md` alongside the §1 matrix, with the `migrates` rows pointing to the migration scripts and the `does-not-persist` rows pointing to their fallback projection surface. The table is the canonical reference for cross-harness skill authorship that depends on durable memory.
+
+Stale memory-convention detection: a memory-convention cell whose snapshot-date diverges from current vendor reality (e.g., the vendor introduced a memory surface after the pin's snapshot date) surfaces as a finding per the stale-pin discipline.
+
+## Enforcement
+
+Path-filtered (the four glob patterns in this rule's `pathFilter` field — `**/src/apothem/harnesses/**`, `**/_inputs/cross-harness-agent-capability-matrix.md`, `**/.mcp.json`, `**/mcp.json`), demand-loaded companion to `rules/agent-capability-discipline.md` §1 / §3 / §7. The parent rule retains the standing directive, the plain-language boundary, the disclosure surface, the failure tells, and the bindings; this companion carries the per-harness capability matrix, the MCP-surface catalog, and the agent-memory-convention catalog.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** ● Every adapter sub-package's per-capability cell value declaration co-resident with its STANDARD CONVENTION PIN. ● The aggregate cross-harness matrix materialization at `_inputs/cross-harness-agent-capability-matrix.md`. ● Every per-harness MCP-surface projection from the profile's MCP inventory. ● Every per-harness agent-memory-convention declaration and its cross-harness portability mapping.
+- **Satisfies →** ● `rules/agent-capability-discipline.md` §1 / §3 / §7 Companion Sub-Rule Anchor pointers. ● The cross-harness adapter capability convergence baseline.
+- **Established by ↑** ● `rules/agent-capability-discipline.md` (parent-rule anchors at §1 / §3 / §7). ● `rules/harness-adapter-shape.md` §4 adapter capability-coverage matrix. ● `rules/harness-adapter-shape.md` §6 STANDARD CONVENTION PIN (the co-resident discipline this companion's evidence chain references).
+- **Gated by ←** ● The path-filter (the four glob patterns) — this rule demand-loads only on adapter / matrix / MCP-config artifact touches. ● `rules/agent-capability-discipline.md` always-on baseline (parent rule's §1 / §3 / §7 anchors must be live for the companion to demand-load coherently).
+- **Cross-bound with ↔** ↔ `rules/agent-capability-discipline.md` (parent rule; §1 / §3 / §7 anchors bind this companion). ↔ `rules/harness-adapter-shape.md` (co-resident STANDARD CONVENTION PIN discipline at §6; per-cell evidence chain anchors to the same pin). ↔ `rules/host-discovery.md` (M1 — per-cell discovery walks the vendor surface per the discovery-record provenance schema). ↔ `rules/disclosure-ledger.md` (M2 — discovery-pending cells and stale-snapshot findings recorded). ↔ `conformity/agent_capability_grep.py` (the mechanical matcher operationalizes the per-cell evidence-chain check). ↔ `rules/source-accessibility.md` (the §1A `web_fetch` column is the backing dimension for that rule's step-1 browser/fetch escalation; reciprocal of its `Gated by ←` web-fetch citation). ↔ `rules/determinism.md` + `rules/option-annotation.md` (the §1B `(Recommended)`-rendering discipline whose per-harness runtime-enforcement wiring this companion catalogs).

package/src/apothem/rules/agent-capability-discipline.md

@@ -0,0 +1,78 @@
+---
+name: "agent-capability-discipline"
+description: "Cross-harness agentic discipline — the 17-harness adapter cohort is recognized as sophisticated AI agent systems; core and supplemental agentic capabilities converge via M14, anchor to per-adapter STANDARD CONVENTION PIN, validate at materializer time, and attest through adapter capability coverage."
+pathFilter: ""
+alwaysApply: true
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Agent Capability Discipline
+
+## What this rule enforces
+
+Binds cross-harness agentic discipline across the 17-harness adapter cohort (**antigravity, claude_code, codebuddy, codex, cursor, gemini_cli, github_copilot, hermes, kimi_code, kiro, open_claw, opencode, qwen_code, trae, windsurf, zed, glm**). Each adapter targets a sophisticated AI agent system. Core and supplemental capabilities MUST discover per vendor doc + commit-SHA-pinned snapshot (or adapter-local convention pin) co-resident with the adapter's STANDARD CONVENTION PIN per `rules/harness-adapter-shape.md` §6, project via M14, validate at materializer time, and attest through capability-coverage. No capability is assumed: every cell is evidence-backed or discovery-pending.
+
+## Pre-conditions
+
+Applies on adapter, capability, and convergence touches.
+
+## Required behavior
+
+### 1. Per-harness agentic-capability matrix (Companion Sub-Rule Anchor)
+
+Core dimensions per adapter: MCP server · sub-agent dispatch · tool-surface restriction · system-prompt template · agent-memory · output-style · custom-command · hooks-pipeline · skills-directory. Supplemental dimensions include recommended-postfix rendering and long-context/compaction continuity. See `rules/agent-capability-discipline-matrix.md` §1.
+
+### 2. Cross-harness sibling-convergence
+
+Operator workflows project per-harness via `rules/systemic-participation.md` M14. A capability present in one adapter MUST project into every cohort sibling whose vendor supports it; divergences MUST be declared — silent omission is a silo finding.
+
+### 3. MCP registry / discovery / sharing (Companion Sub-Rule Anchor)
+
+Profile carries canonical MCP inventory; per-harness materializers project into native surfaces. See `rules/agent-capability-discipline-matrix.md` §3.
+
+### 4. Sub-agent dispatch
+
+Kebab-case names; per-harness ratified file shape. A sub-agent's tool-restriction boundary MUST equal its parent's allow-list intersected with its own restrictions — never widening the parent's. Return-contract per `rules/agent-orchestration.md` §3; converge across the cohort.
+
+### 5. Tool-surface restriction
+
+The universal-deny floor binds regardless of any per-harness allow-list: secrets paths (`.env*`, `~/.ssh/**`, credentials), destructive shell ops (`rm -rf:*`, `sudo:*`, `git push --force*`), network-write to unsigned endpoints. No override silently widens it.
+
+### 6. System-prompt template
+
+Profile system-prompt content projects into each harness's native template; overrides MUST cite a concrete driver per `rules/interactive-questions-canonical-shapes.md` §3.2.1.
+
+### 7. Agent-memory convention (Companion Sub-Rule Anchor)
+
+Per-harness memory semantics: persists / does-not-persist / migrates. See `rules/agent-capability-discipline-matrix.md` §7.
+
+### 8. Materializer detection + post-install validation
+
+Materializers MUST probe vendor support before emission. When a profile declares a capability the pinned snapshot lacks, the materializer refuses unless the operator overrides via `rules/interactive-questions.md` §6. Post-install re-probe surfaces drift as a finding.
+
+### 9. Agent-Capability Coverage attestation
+
+The adapter matrix per `rules/harness-adapter-shape.md` §4 carries a capability-coverage column: every §1 capability MUST have a covering test, attested in the adapter's gate block per `rules/pre-emission-gate.md`.
+
+## Plain-language boundary
+
+Agentic vocabulary (AI / agent / sub-agent / MCP / tool-surface / harness names) is in-scope process-artifact vocabulary for adapter sub-packages, materializers, dev tech-spec, rule-tier. User-facing landing prose remains under `rules/plain-language.md`; this rule does not relax that boundary.
+
+## Disclosure surface
+
+- `[Discovery — source: <harness>/STANDARD-CONVENTION-PIN.md; capability: <name>; vendor-support: <yes | no | partial>; honored]`
+- `[Divergence — harness: <name>; capability: <name>; rationale: <concrete-driver>]`
+- `[Refusal — materializer: <harness>; capability: <name>; reason: vendor-snapshot lacks support; operator-override: <yes | no>]`
+
+## Failure tells
+
+Profile declares unsupported capability without §8 refusal. Sub-agent widens universal-deny without divergence record. Skill projected into one harness, silently omitted from another despite vendor support. Capability-coverage column blank. User-facing surface leaks agentic vocabulary outside in-scope boundary.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** Adapter capability declarations co-resident with STANDARD CONVENTION PIN; materializer vendor-support probes; adapter capability-coverage attestation; the matcher `conformity/agent_capability_grep.py`.
+- **Satisfies →** The cross-harness agentic-discipline baseline; `rules/harness-adapter-shape.md` §4 capability-coverage matrix; `rules/harness-adapter-shape.md` §6 STANDARD CONVENTION PIN discipline.
+- **Established by ↑** `rules/harness-adapter-shape.md` §4 and §6; `CLAUDE.md` Harness Adapter Pattern section.
+- **Gated by ←** `CLAUDE.md` preamble; `rules/plain-language.md` boundary.
+- **Cross-bound with ↔** `rules/agent-capability-discipline-matrix.md` (companion §1 / §3 / §7); `rules/harness-adapter-shape.md` (PIN §6); `rules/plain-language.md`; `rules/systemic-participation.md` (M14); `rules/agent-orchestration.md` (CM-17 / CM-25); `rules/interactive-questions.md` (§6); `conformity/agent_capability_grep.py`.

package/src/apothem/rules/agent-orchestration-patterns.md

@@ -0,0 +1,144 @@
+---
+name: "agent-orchestration-patterns"
+description: "Path-filtered companion sub-rule carrying the team-pattern catalog, agent-type selection, launch protocol, return-contract enforcement, isolation discipline, error handling, decision tree, and anti-patterns that the parent `agent-orchestration.md` rule's anchors declare."
+pathFilter: "**/agents/**/*.md, **/commands/plan-*.md, **/skills/**/SKILL.md, **/rules/agent-orchestration*.md"
+alwaysApply: false
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Agent Orchestration Patterns (Companion Sub-Rule)
+
+## Purpose
+
+Carry the operational detail of agent and agent-team orchestration the parent `rules/agent-orchestration.md` rule's anchors point to. Demand-loaded when the assistant edits agent definitions, plan-pipeline commands, skills, or the parent rule. The parent retains the standing directive, the heuristic summary, the return-contract invariant, and the seriousness-scaling table; this companion carries the six team patterns, the agent-type-selection menu, the launch-protocol detail, return-contract enforcement, isolation/non-duplication detail, error handling, the decision-tree diagram, and the anti-pattern list.
+
+## Obligations
+
+### 1. Agent Team Patterns
+
+Six canonical team patterns — match the pattern to the job. The **Agent Class** column names the harness-neutral agent capability the pattern needs; §2.2 maps each class to a concrete per-harness realization.
+
+| Team Pattern | Purpose | Agent Class | Parallelism | Return Contract |
+| ------------ | ------- | ----------- | ----------- | --------------- |
+| **Research Team** | Information gathering, codebase exploration, skill scanning | read-only exploration agent | Full parallel | Structured summary, max 500 tokens per agent |
+| **Audit Team** | Consistency checks, traceability, verification, spot-checks | full-tool multi-step agent | Full parallel | Pass/fail verdict + evidence citations |
+| **Implementation Team** | Parallel non-overlapping code changes, file writes | full-tool multi-step agent | Parallel (non-overlapping files only) | Confirmation + file list + diff summary |
+| **Generation Team** | Parallel file creation (plan artifacts, docs, reports) | full-tool multi-step agent | Full parallel (one file per agent) | Confirmation + generated file path |
+| **Quality Team** | Parallel quality gates (lint, test, type-check, security) | full-tool multi-step agent | Full parallel | Pass/fail + failure details |
+| **Documentation Team** | Parallel doc/guide updates | full-tool multi-step agent | Full parallel (non-overlapping files) | Confirmation + updated file path |
+
+### 2. Deployment Decision Framework
+
+**2.1 — Deployment Decision.** **Deploy** when ANY holds: 3+ independent parallel operations, multi-path exploration, heavy reads that bloat the main context, multi-dimension verification, or multi-file generation. **Skip** when ANY holds: <3 total operations, tightly-coupled sequential steps, coordination overhead exceeds the parallelism benefit, or the main context already holds the needed information.
+
+**2.1.1 — Spawn-Overhead Threshold (measurement insight).** Per-task agent spawn (a separate harness session) costs ~5-30s of latency on most hosts; in-process parallelism via `src/apothem/lib/parallel_sweep.py` ProcessPoolExecutor costs ~50-300ms per worker on Windows (~10-50ms on POSIX). Both carry non-trivial fixed costs that dominate when per-task work is small. Concrete dispatch decisions:
+
+- **Research Team (parallel exploration).** Deploy when each agent reads 5+ files or pursues a distinct thread — per-agent work (reads + pattern matching + summary synthesis) takes seconds, amortizing spawn overhead. **Skip** when one Read or Grep answers the question — direct dispatch beats spawn.
+- **Quality Team (parallel lint/test/type-check).** Deploy when the host has 3+ independent gates each taking seconds-to-minutes (full pytest, full ruff scan, full `mypy --strict`) — spawn overhead is dwarfed by gate runtime. **Skip** for sub-second linters or single-file checks.
+- **Generation Team (parallel non-overlapping authorship).** Deploy when generating 3+ artifacts each needing substantial composition (a fresh skill, rule, or ADR). **Skip** for small-scope edits, or when artifacts carry substantive cross-references needing post-spawn reconciliation.
+- **In-process parallelism via `src/apothem/lib/parallel_sweep.py`** fits cross-file sweeps where per-file work is **substantial** (≥ 50ms/file, ≥ 20 files). Measured: at 0.67ms-per-matcher on the conformity-gate orchestrator, ProcessPoolExecutor would slow the work 150-450× rather than speed it up. The module documents its when-to-use-vs-avoid criteria.
+
+**2.1.2 — Standing Delegation Default (lean-context posture).** Beyond the §2.1 deploy/skip thresholds, a **standing routing default** governs *where* delegable work runs once the host exposes agent / subagent dispatch: broad reads, large-corpus consumption, and heavy single-thread workloads SHOULD route to a spawned agent **by default** rather than executing in the main context, so the main conversation stays lean and the synthesized result — not the raw corpus — returns. This is a SHOULD posture on routing, not a third deploy trigger and not an obligation: it neither lowers the §2.1 deploy thresholds for *parallel team* dispatch nor makes the heavy multi-agent apparatus a clean-install default. The apparatus stays default-off per `rules/agnostic-posture.md` §1; this default reads alongside it as advisory guidance that activates only when (a) dispatch is reachable and (b) the workload is broad/heavy enough that keeping it out of the main context is the lean choice. Where no dispatch surface exists, the work runs in the main context with the size-aware read discipline of `rules/large-file-reading.md`. The parent rule (`rules/agent-orchestration.md` §2) carries the one-line standing-default summary; this subsection is its operational backing.
+
+**2.2 — Agent Class Selection.** Each class names a harness-neutral capability; select by the work the subtask needs, then map the class to whatever the active harness exposes. Where the harness offers no matching agent surface, fall back to direct in-context tools.
+
+- **Read-only exploration agent.** Codebase exploration, file discovery, pattern searching. Where the harness supports a thoroughness knob, scale it to the scope (targeted lookup, moderate sweep, exhaustive analysis). *Per-harness mapping (one of many):* on the claude_code harness, dispatch a `subagent_type: Explore` agent and set its thoroughness parameter.
+- **Full-tool multi-step agent.** Tasks needing full tool access (reads, writes, shell). The prompt states the deliverable explicitly. *Per-harness mapping (one of many):* on the claude_code harness, dispatch a `subagent_type: general-purpose` agent.
+- **Architecture/planning agent.** Implementation planning and design evaluation. Read-only; returns plans, not modifications. Ad-hoc deployment only (no team pattern). *Per-harness mapping (one of many):* on the claude_code harness, dispatch a `subagent_type: Plan` agent.
+- **Lightweight tier — host low-cost model.** Quick straightforward subtasks (token counting, simple formatting, straightforward checks).
+- **Balanced tier — host general-purpose model.** Moderate-complexity subtasks (code analysis, structured generation, standard verification).
+- **Deep-reasoning tier — explicitly-requested high-capability model.** High-complexity subtasks (architectural decisions, forensic audits, nuanced analysis), only where the host exposes model selection and the extra cost is justified.
+
+### 3. Launch Protocol
+
+**3.1 — Prompt Engineering.** Every agent prompt MUST carry six elements:
+
+- **Mission** — a clear, specific statement of what the agent must accomplish.
+- **Deliverable** — the exact format and content of the expected return (e.g., "Return a JSON object with keys: status, findings, evidence").
+- **Constraints** — boundaries on what the agent MUST NOT do (e.g., "Do NOT modify any files", "Do NOT read more than 10 files").
+- **Context** — essential context not available in the codebase (decisions made earlier in the conversation, user preferences).
+- **Return contract** — the maximum token budget for the return payload. Defaults: 500 (research), 200 (audit/quality), 500 (implementation/documentation), 1000 (generation). Persistent agent definitions (`agents/*.md`) MAY override these defaults.
+- **File scope (Implementation Teams only)** — the exclusive file set the agent MAY modify. No two parallel agents share a file in their scope; verify non-overlap before launch.
+
+**3.2 — Parallel Launch.** Launch all independent agents in a SINGLE turn using the harness's agent-dispatch surface (one dispatch per agent). Never launch independent agents sequentially. Group dependent agents into waves: Wave 1 (independent) → collect results → Wave 2 (dependent on Wave 1). *Per-harness mapping (one of many):* on the claude_code harness, emit multiple Agent tool calls in one message.
+
+**3.3 — Background vs. Foreground.**
+
+- **Foreground (default)** — when results are needed before proceeding; the norm for research, audit, and quality teams.
+- **Background — where the harness exposes a detached-dispatch mode.** When genuinely-independent work runs concurrently (comprehensive test suites, large-scale generation, deep exploration), dispatch the agent in the background and do NOT poll or sleep — completion notifies you. *Per-harness mapping (one of many):* on the claude_code harness, pass `run_in_background: true`. Where the harness has no detached mode, run the work in the foreground or sequence it.
+
+### 4. Return Contract Enforcement
+
+**4.1 — Contract Specification.** Every launch MUST specify the contract in the prompt: expected format, maximum size, required fields, and the fallback shape when the agent cannot fulfill it (e.g., "If no matching files found, return `{status: 'empty', reason: '...'}`").
+
+**4.2 — Result Processing.** Process all parallel results in a single pass, never piecemeal. Verify each against its contract. A result over budget: extract only the critical fields, discard the verbose output. A malformed or incomplete result: log the failure, then retry once or proceed without that agent's contribution.
+
+**4.3 — Context Integration.** Synthesize a compact summary and release the raw results from active context. Externalize per `rules/context-management.md` §2.1 when results contain decisions; otherwise externalize synthesized results with lasting value. Never hold raw agent output beyond the turn it is processed.
+
+### 5. Isolation and Non-Duplication
+
+**5.1 — Work Isolation.** Each agent operates on a defined, non-overlapping scope. Two agents touching the same file MUST NOT run in parallel — sequence them. When agents make independent changes that share write paths, use the harness's per-agent isolation surface where one exists (a temporary git worktree per agent so parallel writes do not collide). Verify the harness exposes such a surface before relying on it; if absent, sequence the agents. *Per-harness mapping (one of many):* on the claude_code harness, set the Agent tool's `isolation: "worktree"` parameter.
+
+**5.2 — Non-Duplication.** The main context MUST NOT perform research an agent is performing, nor re-read files an agent is reading unless the results are insufficient. Track which agents do what; prevent redundant work.
+
+**5.3 — Coherence Verification.** After parallel agents complete, verify their outputs are mutually consistent. Contradictory findings are investigated and resolved before proceeding. For Implementation Teams: verify parallel code changes integrate — run tests/builds after merging.
+
+### 6. Error Handling and Recovery
+
+- **Agent timeout.** Continue other work — completion notifies you. Do NOT spawn a duplicate.
+- **Agent failure.** Log it; retry once with a refined prompt; on a second failure, proceed without that agent's contribution and document the gap.
+- **Parallel team failure threshold.** When 2+ agents in the same team fail (including retries), treat the team result as degraded — inform the user of the coverage gap before proceeding. CM-18 escalation (3 cumulative failures) applies across all teams in the session, not per-team.
+- **Result conflict.** Escalate contradictory results to the main context; never silently pick one.
+- **Context pressure from results.** Process in batches — synthesize batch 1, externalize, release, then batch 2.
+
+## Decision Tree
+
+```mermaid
+%%{ init: { "theme": "neutral" } }%%
+%% verified: 2026-04-27 %%
+%% provenance: rules/agent-orchestration-patterns.md §2.1 (deployment decision) + §2.2 (agent type selection) %%
+%% cross-reference: rules/agent-orchestration-patterns.md §Decision Tree (in-rule per-subagent dispatch tree) %%
+flowchart TD
+    Start[Orchestrator considers offloading work] --> Q1{3+ independent operations OR multi-path exploration OR heavy reads OR multi-dimension verification?}
+    Q1 -->|no| Direct[Skip subagent · use direct tools]
+    Q1 -->|yes| Q2{Task class}
+    Q2 -->|Read-only exploration| Explore[Read-only exploration agent · specify thoroughness]
+    Q2 -->|Architectural planning| Plan[Architecture/planning agent · ad-hoc only]
+    Q2 -->|Multi-step write or build| GP[Full-tool multi-step agent · enumerate file scope]
+    Explore --> Q3{Multiple independent agents to launch?}
+    Plan --> Q3
+    GP --> Q3
+    Q3 -->|yes| Parallel[Launch all in single turn · non-overlapping file scopes]
+    Q3 -->|no| Solo[Launch single agent]
+    Parallel --> Q4{Agents touch same file?}
+    Q4 -->|yes| Worktree[Use harness isolation surface OR sequence agents]
+    Q4 -->|no| Contract[Specify return contract per task class]
+    Solo --> Contract
+    Worktree --> Contract
+    Contract --> Synth[Synthesize · release raw output · externalize per CM-24]
+    Synth --> Q5{Outputs consistent across agents?}
+    Q5 -->|no| Resolve[Investigate contradictions · escalate to main context]
+    Q5 -->|yes| Done[Integrate results]
+```
+
+## Anti-Patterns
+
+- **DON'T** launch a single agent for a task that a direct tool call can handle — **BECAUSE** agent overhead (prompt, launch, result processing) exceeds the benefit for single-operation tasks.
+- **DON'T** launch agents sequentially when they have no dependencies between them — **BECAUSE** sequential launch wastes time proportional to the number of agents.
+- **DON'T** duplicate work between the main context and agents — **BECAUSE** it wastes tokens and risks contradictory results.
+- **DON'T** hold raw agent results in context after processing — **BECAUSE** verbose results consume context budget without ongoing value.
+- **DON'T** launch agents without explicit return contracts — **BECAUSE** unbounded returns bloat the main context and create unpredictable token consumption.
+- **DON'T** use the deep-reasoning tier for simple verification tasks — **BECAUSE** the lightweight or balanced tier accomplishes the same result at lower cost and latency.
+
+## Enforcement
+
+Path-filtered (the four glob patterns in this rule's `pathFilter` field), always-on at every seriousness level when in scope. Demand-loaded companion to `rules/agent-orchestration.md`. The parent rule carries the standing directive, the deployment-heuristic summary, the return-contract invariant statement, and the seriousness-scaling table; this companion carries the team-pattern catalog, the agent-type-selection menu, the launch-protocol detail, return-contract enforcement bodies, isolation/non-duplication detail, error-handling detail, the decision-tree diagram, and the anti-pattern list.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** ● Every agent deployment decision's pattern selection (§1 team-pattern catalog). ● Every parallel agent team launch (§3.2 single-message parallel-launch invariant). ● Every agent prompt's six-element shape (§3.1 prompt engineering). ● Every return-contract enforcement loop (§4 contract specification + result processing + context integration). ● The Implementation Team file-scope-non-overlap invariant (§3.1 file scope; §5.1 isolation worktree).
+- **Satisfies →** ● CM-17 (Agent Teams) and CM-25 (Agent Orchestration; rule-delegated). ● the rules registry row "Agent Orchestration" (companion-tier specification). ● `rules/agent-orchestration.md` Companion Sub-Rule Anchor (the parent rule's pointer to this companion's full specification).
+- **Established by ↑** ● `rules/agent-orchestration.md` (parent-rule anchor). ● CM-17 + CM-25. ● the agents registry (the persistent agent definitions consume this companion's deployment patterns).
+- **Gated by ←** ● The path-filter (`**/agents/**/*.md`, `**/commands/plan-*.md`, `**/skills/**/SKILL.md`, `**/rules/agent-orchestration*.md`) — this rule demand-loads only on agent-orchestration-touching artifact edits. ● `rules/agent-orchestration.md` always-on baseline (parent rule must be live for the companion anchor to surface).
+- **Cross-bound with ↔** ↔ `rules/agent-orchestration.md` (parent rule; the Companion Sub-Rule Anchor binds this companion). ↔ `agents/codebase-explorer.md` + `agents/convention-auditor.md` + `agents/quality-gate.md` + `agents/memory-auditor.md` (the four persistent flat agent definitions this companion's §1 team patterns dispatch to). ↔ `rules/agent-orchestration-patterns.md` §Decision Tree (the in-rule per-agent dispatch tree the §2.2 agent-class-selection cross-references). ↔ `rules/context-management.md` (post-multi-agent compaction trigger; §6 result-processing externalizes agent results per CM-24). ↔ `rules/operational-mandates.md` (CM-17 + CM-25 inline-defined there).

package/src/apothem/rules/agent-orchestration.md

@@ -0,0 +1,65 @@
+---
+name: "agent-orchestration"
+description: "Agent and agent team orchestration — the six canonical team patterns (Research, Audit, Implementation, Generation, Quality, Documentation), the deploy-when threshold (3+ independent parallel operations, multi-path exploration, heavy reads, multi-dimension verification, multi-file generation), the single-message parallel-launch invariant, explicit return contracts, and context isolation. Canonical specification for CM-17 / CM-25."
+pathFilter: ""
+alwaysApply: true
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Agent Orchestration
+
+## Purpose
+
+Govern agent deployment: maximize parallelism, enforce return contracts, isolate context, prevent duplication and contradiction. Canonical specification for CM-17 (Agent Teams) and CM-25 (Agent Orchestration).
+
+## Obligations
+
+### 1. Standing Directive
+
+Deploy agent teams to maximize parallelism, enforce return contracts, isolate context, and prevent duplication and contradiction. Six canonical team patterns — **Research**, **Audit**, **Implementation**, **Generation**, **Quality**, **Documentation** — each binding an agent type, a parallelism shape, and a return-contract template. (Companion Sub-Rule Anchor) See `rules/agent-orchestration-patterns.md` §1 for the full team-pattern catalog.
+
+### 2. Deployment Heuristic
+
+**Deploy** when ANY holds: 3+ independent parallel operations, multi-path exploration, heavy reads that bloat the main context, multi-dimension verification, or multi-file generation. **Skip** when ANY holds: <3 operations, tightly-coupled sequential steps, coordination overhead exceeds the parallelism benefit, or the main context already holds the needed information.
+
+**Standing delegation default (lean-context posture).** Where the host exposes agent / subagent dispatch, broad reads, large-corpus consumption, and heavy workloads SHOULD route to a spawned agent **by default** — keeping the main context lean is the standing posture, not only the explicit opt-in path. This is advisory SHOULD-guidance about *where* delegable work runs when dispatch is available; it never makes the heavy multi-agent apparatus a clean-install obligation. The apparatus itself stays default-off per `rules/agnostic-posture.md` §1; this default governs only routing once delegation is reachable. Where the host exposes no dispatch surface, the work runs in the main context. (Companion Sub-Rule Anchor) See `rules/agent-orchestration-patterns.md` §2 for agent-type selection (`Explore` / `general-purpose` / `Plan`) and model-tier selection (lightweight / balanced / deep-reasoning).
+
+### 3. Launch Protocol
+
+Every agent prompt MUST carry six elements: Mission + Deliverable + Constraints + Context + Return contract + File scope (Implementation Teams). Independent agents MUST launch in a SINGLE message with multiple Agent tool calls; dependent agents are grouped into waves (Wave 1 independent → collect → Wave 2 dependent). Foreground is the default; `run_in_background: true` is for genuinely-independent long-running work — never poll or sleep. (Companion Sub-Rule Anchor) See `rules/agent-orchestration-patterns.md` §3 for the full prompt-engineering, parallel-launch, and background/foreground specification.
+
+### 4. Return Contract Invariant
+
+Every agent launch MUST specify an explicit return contract: format, maximum size, required fields, and fallback shape. Results are processed in a single pass, verified against the contract, synthesized into a compact summary, and the raw output is released — never held in context beyond the turn it is processed. (Companion Sub-Rule Anchor) See `rules/agent-orchestration-patterns.md` §4 for contract-specification, result-processing, and context-integration detail.
+
+### 5. Isolation, Non-Duplication, Error Handling
+
+Each agent operates on a non-overlapping scope; agents touching the same file MUST be sequenced or use `isolation: "worktree"`. The main context MUST NOT duplicate work an agent is performing. Parallel outputs are checked for consistency before integration. Timeouts continue; failures retry once; 2+ team failures degrade the team result; contradictions escalate to the main context. (Companion Sub-Rule Anchor) See `rules/agent-orchestration-patterns.md` §5–§6 for isolation, non-duplication, coherence-verification, and error-handling detail.
+
+### 6. Decision Tree and Anti-Patterns
+
+The orchestration decision tree (deploy / skip → agent type → parallel / solo → isolation → return contract → synthesize) and the six canonical anti-patterns (single-agent-for-direct-tool-task, sequential-when-parallel, main-context-duplicating-agent-work, raw-results-held-in-context, no-return-contract, deep-reasoning-on-trivial-task). (Companion Sub-Rule Anchor) See `rules/agent-orchestration-patterns.md` Decision Tree + Anti-Patterns sections.
+
+## Seriousness Scaling
+
+> **Two-axis scaling note.** Unlike most rules (single column), this scaling table tracks two orthogonal dimensions: **deployment requirement** (when to use agents at all) and **agent sophistication** (which model tier to prefer). They scale at different rates with seriousness — e.g., a SHARED project may demand parallel teams (axis 1) while still using balanced-tier models for routine work (axis 2). Read the columns independently.
+
+| Level | Agent Team Requirement | Agent Sophistication |
+| ----- | ---------------------- | -------------------- |
+| EXPLORING | Optional | Lightweight tier for cost efficiency |
+| PERSONAL_USE | Encouraged for parallelizable work | Balanced tier for standard tasks |
+| SHARED | Required for 3+ independent parallel operations — strict return contracts enforced | Deep-reasoning tier for critical decisions, balanced tier for standard |
+| PUBLIC_LAUNCH | Required for 2+ independent operations. Isolation verification after parallel completion | Deep-reasoning tier for all agents touching shared/public artifacts |
+
+## Enforcement
+
+Always-on at every seriousness level, scaling per the table above. Implements CM-17/CM-25. Canonical specification for agent and agent team orchestration.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** ● Every agent deployment decision (§2.1 deployment heuristic; §2.2 agent-type selection). ● Every parallel agent team launch (§3.2 single-message parallel-launch invariant). ● Every agent's return-contract enforcement (§4 contract-specification + result-processing). ● Every `/plan-<stage>` command's agent-team specification (each decomposed plan command's Step 1 cites "Research Team", Step 4 cites "Quality Team", etc., per the canonical six team patterns). ◐ The Implementation Team file-scope-non-overlap invariant (§1 + §3.1 file scope; isolation worktree per §5.1).
+- **Satisfies →** ● CM-17 (Agent Teams) and CM-25 (Agent Orchestration; rule-delegated). ● the rules registry row "Agent Orchestration". ● the agents registry (the four persistent flat `<name>.md` definitions consume this rule's deployment patterns).
+- **Established by ↑** ● CM-17 + CM-25. ● the artifact directories (agents/ directory class declaration). ● the agents registry (the persistent agent definitions).
+- **Gated by ←** ● `CLAUDE.md` always-loaded preamble. ● The harness's agent-spawn capability (Agent tool surface; subagent-type schema). ● `rules/operational-mandates.md` (CM-1 critical evaluation governs the deploy/skip decision at §2.1).
+- **Cross-bound with ↔** ↔ `rules/agent-orchestration-patterns.md` (path-filtered companion sub-rule carrying the team-pattern catalog, agent-type selection, launch protocol, return-contract enforcement, isolation discipline, error handling, decision tree, and anti-patterns). ↔ `agents/codebase-explorer.md` + `agents/convention-auditor.md` + `agents/quality-gate.md` + `agents/memory-auditor.md` (the four persistent flat agent definitions this rule's §1 team patterns dispatch to). ↔ `rules/agent-orchestration-patterns.md` §Decision Tree (the per-subagent dispatch tree the §2.2 agent-type-selection decision tree cross-references). ↔ `rules/context-management.md` (post-multi-agent compaction trigger lives at §3 of that rule; this rule's §6 result-processing externalizes agent results per CM-24). ↔ `rules/operational-mandates.md` (CM-17 + CM-25 inline-defined there; this rule is the canonical specification). ↔ `rules/agent-capability-discipline.md` (CM-17 / CM-25 — agent-capability matrix dispatches under the orchestration patterns declared here). ↔ `rules/agnostic-posture.md` (agent-team dispatch is opt-in under the host-agnostic posture, not a default-on obligation). ↔ `rules/multi-agent-workflow.md` (the independent-critique / open-loop / dynamic multi-agent capability declared there runs through the team-pattern catalog, launch protocol, return contracts, and isolation discipline this rule owns; it references, never duplicates, them). ↔ `rules/refactoring-discipline.md` (§5.1 worktree isolation provides the isolated workspace for one-refactor-at-a-time). ↔ `rules/tool-use-discipline.md` (the §3 single-message parallel-launch invariant this rule binds at the agent tier is generalized down to ordinary tool calls there).