Release/mambo v3

.agents/README.md

@@ -49,11 +49,22 @@ from file paths, independently of the message prefix. See
 
 ## Maintenance
 
-Use the [note format](notes/README.md). Maintain one note per coherent topic, with
-an explicit status and last verification date. When work finishes, close or
-supersede the note and promote developer-relevant conclusions to their canonical
-docs. Remove obsolete duplication; Git preserves history. No session-by-session
-journal, parallel roadmap or automatic archive tree is required.
-
-Existing developer roadmaps, benchmark evidence and execution plans remain where
-they are. Being produced by an agent does not make them agent-only documentation.
+Keep tracked explanations and evidence only when they are highly useful for a
+current decision, maintained workflow or likely future development. Uniqueness
+alone is not a reason to retain a finding. Condense superseded investigations to
+their consequential conclusion and provenance; use Git for the detailed history.
+
+Keep one maintained home for each contract, procedure, result and backlog item.
+Update that section when evidence changes instead of appending another dated fix
+or campaign recap. Link from indexes rather than copying explanations or tables.
+Developer documents stay in `docs/`/`dev/`; authorship does not make them agent notes.
+
+Use [handoffs](notes/README.md) only for unresolved cross-session work. On completion,
+promote useful conclusions and remove redundant notes; Git is the history. Retain
+raw evidence, provenance and consequential negative results where reproducibility
+needs them, without duplicating every experiment's presentation in maintained docs.
+Before retiring a page or figure, check inbound links, generators and release assets.
+
+A new document needs a distinct audience/purpose that an existing page cannot serve.
+Prefer a concise update or link. Cleanup should improve decisions and findability,
+not merely minify text or relocate it into another archive tree.

.agents/notes/README.md

@@ -1,40 +1,21 @@
-# Agent notes
+# Agent handoffs
 
-Use `YYYY-MM-DD-short-topic.md` (creation date) for a durable handoff or focused
-research note. Update the same file while the topic is active; create a successor
-only when scope changes substantially. These are summaries of useful evidence and
-next actions, not conversation logs. Do not create notes for routine edits.
+No active tracked handoffs. Completed migration, policy-research and quantization
+cleanup notes were retired after their useful content was consolidated into
+[workspace policy](../README.md), [CI guidance](../../dev/README.md#agent-only-changes-and-ci)
+and [artifact retention](../../docs/quantization-artifacts.md). Git retains history.
 
-Use this structure, omitting empty sections:
+Create `YYYY-MM-DD-topic.md` only for a cross-session handoff that cannot live in an
+existing maintained guide. Update the same topic; do not create per-session notes.
+Keep scratch, raw logs and measurements in ignored `../local/` or the evidence store.
 
-```markdown
-# Topic
+Use a short title, status/date, scope and related commit/document, followed by:
 
-Status: active | completed | superseded
-Updated: YYYY-MM-DD
-Scope: relevant paths or subsystem
-Related: implementation commit, issue, or canonical document
+- **Decision and reason:** only context needed to continue the work.
+- **Evidence and limits:** source identities, useful observations and what is unverified.
+- **Remaining work:** concrete next actions and where their outcome will be maintained.
 
-## Context and decision
-What was requested, what was chosen, and why.
-
-## Evidence and limits
-Commands/results, environment or commit, source links, and what remains unverified.
-Distinguish observed behavior from a hypothesis or recommendation.
-
-## Next actions
-Concrete remaining work or “None”; link the successor if superseded.
-```
-
-Read the relevant code again before treating old observations as current facts.
-Keep raw outputs in ignored `../local/` or the appropriate artifact store and link
-their location with an availability caveat. Commit notes separately using `agent:`.
-
-Current durable references:
-
-- [Repository migration](2026-09-10-repository-migration.md) — completed; audit
-  findings and the two approved migration commits.
-- [Quantization cleanup handoff](2026-09-09-quantization-cleanup.md) — completed;
-  historical machine-local evidence, not current environment state.
-- [Repository agent workflow research](2026-09-10-agent-workflow.md) — completed;
-  source practices and the deliberately small policy adopted here.
+Recheck old observations before treating them as current. When work closes, promote
+useful conclusions to the canonical guide and remove the redundant handoff. Preserve
+unique evidence with provenance when it still informs a decision. Commit agent-only
+material separately with `agent:`; never store credentials or private reasoning.

.agents/rules/code-contribution.md

@@ -8,3 +8,56 @@ its callers before changing it. Keep behavior fixes separate from mechanical cle
 Follow [the agent workspace policy](../README.md) for note locations and separate
 `agent:` commits. Keep application changes and developer-facing docs out of those
 commits; the prefix records purpose, not authorship.
+
+## Choosing fixes and experiments
+
+- Start from the user's intended outcome and constraints. When corrected about
+  priorities or scope, revise the proposed work instead of repeatedly defending
+  the previous approach. For deployment, count recurring developer effort across
+  environments as part of the cost, alongside implementation complexity.
+- Separate the observed failure, suspected mechanism, and the layer we control.
+  Prefer the smallest durable change in that layer, using existing package-manager
+  and framework capabilities. A kernel workaround, diagnostic probe, or clearer
+  error may help investigation; identify whether it prevents the failure or only
+  detects/contains it. Do not present a guardrail as a compatibility fix.
+- Test cheap, reversible hypotheses before adding custom infrastructure or
+  repeatedly debating their limitations. State what the experiment changes, what
+  result would support it, and what remains uncertain. Inspect environment details
+  when they distinguish hypotheses or guide action, rather than as an end in itself.
+- For dependency hypotheses, test the actual resolved and installed environment
+  in isolation. Changing version ranges while retaining the same locked packages
+  does not test fresh resolution. Compare installed versions and exercise real
+  inference; successful dependency resolution alone is insufficient. Follow the
+  root README's environment conventions and preserve working environments.
+- Distinguish reproducibility within an evaluation campaign from adaptability of
+  deployment installation. Preserve resolved versions as evidence without assuming
+  one evaluation lock must govern all future installations. Neither removing locks
+  nor pinning versions is automatically a compatibility solution.
+- Use available representative environments for bounded qualification. Agreement
+  across them supports a practical improvement without proving universal support
+  or identifying which changed dependency caused it. Expand the matrix or isolate
+  individual changes when that would change the decision; do not require exhaustive
+  architecture access before trying a useful fix.
+- Review the complete operator workflow before handing it over. Minimize new flags,
+  configuration copies, path edits, and environment switches; count these as real
+  complexity even when the code is short. If a setup change alters paths or commands,
+  update downstream steps consistently rather than asking users to translate them.
+  State exactly what must be rerun and what existing assets/results can be reused.
+
+## Keeping tests useful
+
+Give each test a failure contract. Before adding one, check existing coverage;
+parameterize genuinely equivalent cases and share repeated setup locally. Prefer
+observable outputs, errors and ownership/lifetime guarantees to source-text checks
+or assertions that repeat configuration literals. Keep performance guards only
+when they detect a documented cost mechanism without machine-specific timing.
+
+Retire tests for retired tools and assertions that merely freeze transient
+experiment matrices, private helper structure or mutable presentation. An
+elaborate fixture is justified by the failure it detects, not by existing coverage
+alone. Do not preserve obsolete behavior just to preserve its tests.
+
+When consolidating, preserve distinct regression cases, skip/xfail meaning and
+checkpoint/spawn fixture identities. Fewer lines or cases are secondary to simpler
+coverage with the same fault detection. Do not add a generic fixture framework or
+rerun expensive suites for documentation-only edits.