chore: add agent_instructions methodology layer

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

.machine_readable/agent_instructions/README.adoc

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+= Agent Instructions
+:toc: preamble
+
+Methodology-aware configuration for AI agents. Read by any AI agent
+(Claude, Gemini, Copilot, etc.) at session start.
+
+== Files
+
+[cols="1,3"]
+|===
+| File | Purpose
+
+| `methodology.a2ml`
+| Default mode, invariants, ring ceiling, priority weights, convergent budget
+
+| `coverage.a2ml`
+| Session coverage tracking — what was visited, what was skipped, what has MUSTs
+
+| `debt.a2ml`
+| Meander debt — things found but not fixed, carried between sessions
+|===
+
+== How Agents Use These
+
+1. Read `methodology.a2ml` at session start — know mode, invariants, ceiling
+2. Read `coverage.a2ml` — know what was visited last time, what was skipped
+3. Read `debt.a2ml` — know what's outstanding from previous sessions
+4. At session end, update `coverage.a2ml` and `debt.a2ml`
+
+== Relationship to Other Files
+
+* `AGENTIC.a2ml` says WHAT agents can do (permissions, gating)
+* `agent_instructions/` says HOW agents should work (methodology)
+* `bot_directives/` says what the gitbot-fleet does (fleet-specific)
+* `CLAUDE.md` says how Claude specifically should work (Claude-specific)
+
+== Reference
+
+ADR-002 in `standards/agentic-a2ml/docs/ADR-002-methodology-layer.adoc`

.machine_readable/agent_instructions/coverage.a2ml

@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# coverage.a2ml — Session coverage tracking
+# Updated at the end of each AI agent session.
+# Persists what was visited, what was skipped, and what has MUSTs.
+#
+# Reference: ADR-002 in standards/agentic-a2ml/docs/
+
+[metadata]
+version = "1.0.0"
+last-updated = "2026-03-24"
+
+# ============================================================================
+# COVERAGE STATE
+# ============================================================================
+# Updated by agents at session end. Tracks which components have been
+# visited and which have known MUSTs that were skipped.
+
+[coverage]
+total-components = 0
+visited-components = 0
+coverage-percent = 0
+
+# ============================================================================
+# VISITED COMPONENTS
+# ============================================================================
+# Component → session date + ring reached
+# Agents add entries as they work through components.
+#
+# Example:
+# [coverage.visited.emergency-room]
+# date = "2026-03-23"
+# ring = 2
+# fixes = 3
+# notes = "boot-guardian built, shutdown-marshal built"
+
+# ============================================================================
+# SKIPPED COMPONENTS WITH MUSTS
+# ============================================================================
+# Components with known MUSTs that were not visited in the most recent session.
+# These become P1 inputs for the next session's Phase 0.
+#
+# Example:
+# [coverage.skipped-musts.session-sentinel]
+# priority = "P0"
+# issue = "56 SIGABRTs in 4 days, D-Bus race condition"
+# discovered = "2026-03-23"
+
+# ============================================================================
+# CHERRY-PICKING AUDIT
+# ============================================================================
+# At session end, agents report whether they chose easy work over hard work.
+# This is the accountability mechanism for the weighted priority system.
+#
+# [coverage.cherry-picking]
+# easy-high-completed = 3
+# hard-high-completed = 1
+# easy-low-completed = 2
+# hard-low-deferred = 4
+# assessment = "Correctly prioritised — all MUST items addressed before COULDs"

.machine_readable/agent_instructions/debt.a2ml

@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# debt.a2ml — Meander debt list
+# Things found but not fixed. Carried between sessions.
+# Becomes the next session's Phase 0 input.
+#
+# Reference: ADR-002 in standards/agentic-a2ml/docs/
+
+[metadata]
+version = "1.0.0"
+last-updated = "2026-03-24"
+
+# ============================================================================
+# DEBT ITEMS
+# ============================================================================
+# Each item has: component, issue, effort (easy|medium|hard), impact (high|medium|low),
+# priority (should|could), and discovered date.
+#
+# Items are consumed (removed) when fixed. New items are added at session end.
+# The debt list prevents the "one more wave" loop — found things are persisted,
+# not forgotten, and not used as justification for infinite meandering.
+
+# ============================================================================
+# SHOULD — would fix next wave
+# ============================================================================
+# These are inputs for the next session if the user says "keep going".
+#
+# Example:
+# [[debt.should]]
+# component = "system-tools/monitoring/observatory"
+# issue = "Stale duplicate of root observatory/"
+# effort = "easy"
+# impact = "medium"
+# discovered = "2026-03-23"
+
+# ============================================================================
+# COULD — would fix eventually
+# ============================================================================
+# These are low-priority items that don't justify a session on their own.
+# They get picked up when an agent is in the area for other reasons.
+#
+# Example:
+# [[debt.could]]
+# component = "cicada"
+# issue = "RSR_OUTLINE.adoc references banned AGPL-3.0"
+# effort = "easy"
+# impact = "low"
+# discovered = "2026-03-23"

.machine_readable/agent_instructions/methodology.a2ml

@@ -0,0 +1,107 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# methodology.a2ml — AI agent methodology configuration
+# Declares how agents should approach work in this repository.
+# Read at session start by any AI agent (Claude, Gemini, Copilot, etc.)
+#
+# Reference: ADR-002 in standards/agentic-a2ml/docs/
+
+[metadata]
+version = "1.0.0"
+last-updated = "2026-03-24"
+spec = "https://github.com/hyperpolymath/standards/blob/main/agentic-a2ml/docs/ADR-002-methodology-layer.adoc"
+
+# ============================================================================
+# MODE SELECTION
+# ============================================================================
+# convergent: find gaps, fill them, build infrastructure (default for ops/infra)
+# divergent: find what's strongest, push it further (for research/creative)
+# hybrid: audit 20% of budget, then focus 80% on top MUSTs (default for most)
+
+[methodology]
+default-mode = "hybrid"
+ring-ceiling = 2              # Hard ceiling for ring expansion (0-3)
+wave-cap = 2                  # Max waves before requiring user "keep going"
+spike-required = true         # Every session must ship code, not just designs
+
+# ============================================================================
+# PRIORITY WEIGHTS
+# ============================================================================
+# MUST (3x): Blocking the current work → fix immediately
+# SHOULD (2x): Degrading quality of current work → fix if in zone
+# COULD (1x): Improving quality of adjacent work → add to debt list
+
+[methodology.priority-weights]
+must = 3
+should = 2
+could = 1
+
+# ============================================================================
+# CONVERGENT BUDGET (when mode = convergent or hybrid)
+# ============================================================================
+# How to allocate effort across work types.
+# Prevents over-polishing docs while structural work waits.
+
+[methodology.convergent-budget]
+structural = 70   # % for new modules, compilation fixes, wiring, integration
+corrective = 20   # % for bugs found, broken imports, stale references
+perfective = 10   # % for SPDX headers, doc updates, formatting, style
+
+# ============================================================================
+# UNIQUE STRENGTH (when mode = divergent)
+# ============================================================================
+# What makes this project special. Agents should DEEPEN this, not broaden it.
+# Customise this per project — the template default is generic.
+
+[methodology.unique-strength]
+description = "{{PROJECT_UNIQUE_STRENGTH}}"
+deepen-not-broaden = true
+
+# ============================================================================
+# DIVERGENT INVARIANTS
+# ============================================================================
+# Constraints that divergent mode must NOT violate.
+# These are the riverbanks — diverge within them, not across.
+# "Amplify uniqueness" means deepen, not broaden.
+#
+# Test before any divergent action:
+#   "Does this deepen the existing strength, or add a parallel strength?"
+#   If parallel → stop. Note as cross-project insight.
+
+[methodology.divergent-invariants]
+rules = [
+  # Customise per project. Examples:
+  # "Idris2 only for formal verification — no Lean4, Coq, Agda",
+  # "believe_me count must remain zero",
+  # "FFI architecture: Idris2 → RefC → Zig → C ABI (no shortcuts)",
+]
+
+# Optional: language invariant for the core strength
+# If set, divergent mode will not introduce other languages for this purpose
+# language-invariant = "idris2"
+
+# ============================================================================
+# CONSTRAINT HINTS
+# ============================================================================
+# Help Phase 0 find the critical chain faster.
+# Updated at session end with newly discovered constraints.
+
+[methodology.known-constraints]
+constraints = [
+  # Customise per project. Examples:
+  # "End-to-end build has never been verified",
+  # "libproject.so does not exist yet — all bindings call stubs",
+]
+
+# ============================================================================
+# STATE FILE VALIDATION
+# ============================================================================
+# Phase 0 reads STATE.a2ml first but it may be broken.
+# These rules detect corrupt/template/stale state files.
+
+[methodology.state-validation]
+reject-if-contains = ["{{PLACEHOLDER}}", "{{PROJECT}}", "rsr-template-repo"]
+reject-if-project-name-mismatch = true
+staleness-threshold-days = 90
+fallback-files = ["TODO.md", "TODO.adoc", "ROADMAP.adoc", "README.adoc"]