From 82704ae284d8e7562b5aac53a2207fc0297ba0ba Mon Sep 17 00:00:00 2001 From: Nigel Jones Date: Fri, 31 Jul 2026 08:16:44 +0100 Subject: [PATCH 1/3] docs: mark stale docs/dev/ design notes as outdated docs/dev/ has no currency signal, so contributors and coding agents can follow a design note as if it reflects current behaviour when it does not. Add a short status banner to each file confirmed stale or unfinished during an audit against current source: - intrinsics_and_adapters.md: predates Epic #929's capability-based adapter model; rewrite tracked in #1144 - tool_calling.md: proposes a SessionToolCallingProtocol mixin that was never implemented; the shipped example uses unrelated ad hoc classes - mify.md: example code does not run as written, and the implementation path it cites has moved; points readers to the published replacement and the working example - spans.md: unfinished stub with no SpanContext in the codebase; notes that the old /dev/spans redirect now points to an unrelated page - constrained_decoding.md: informal brainstorm with no recorded decision - mellea_library.md: philosophy statement, not re-verified line-by-line generate_ctx_signature.md, hook_system.md, and requirement_aLoRA_rerouting.md were checked against source and left unchanged; they still match current code. Assisted-by: Claude Code Signed-off-by: Nigel Jones --- docs/dev/constrained_decoding.md | 5 +++++ docs/dev/intrinsics_and_adapters.md | 7 +++++++ docs/dev/mellea_library.md | 4 ++++ docs/dev/mify.md | 8 ++++++++ docs/dev/spans.md | 8 ++++++++ docs/dev/tool_calling.md | 6 ++++++ 6 files changed, 38 insertions(+) diff --git a/docs/dev/constrained_decoding.md b/docs/dev/constrained_decoding.md index 4318443ef..2ef75078b 100644 --- a/docs/dev/constrained_decoding.md +++ b/docs/dev/constrained_decoding.md @@ -1,5 +1,10 @@ # Constrained Decoding +> **Status: informal brainstorm.** This note records open questions and +> unattributed suggestions from an early discussion; no decision was ever +> recorded and nothing below should be treated as settled design. See #1482 +> for the `docs/dev/` currency discussion. + ## How do constraints get defined? Should we be thinking bigger than pydantic? Should it be possible to pass arbitrary grammars? If so, what's the abstract interface for those? Should this be factored out into llm-io? diff --git a/docs/dev/intrinsics_and_adapters.md b/docs/dev/intrinsics_and_adapters.md index 3d1375921..40caa7fc7 100644 --- a/docs/dev/intrinsics_and_adapters.md +++ b/docs/dev/intrinsics_and_adapters.md @@ -1,4 +1,11 @@ # Intrinsics and Adapters + +> **Status: outdated.** "Mellea currently only supports IntrinsicAdapters and +> Intrinsics" predates Epic #929's capability-based `Identity` / `_find_adapter` +> adapter model (see [`requirement_aLoRA_rerouting.md`](requirement_aLoRA_rerouting.md) +> for the current lookup mechanism). A rewrite of this note is tracked in +> #1144. See #1482 for the broader `docs/dev/` currency discussion. + Note: Mellea currently only supports IntrinsicAdapters and Intrinsics. ## Basics diff --git a/docs/dev/mellea_library.md b/docs/dev/mellea_library.md index 3baf14898..7b476dd09 100644 --- a/docs/dev/mellea_library.md +++ b/docs/dev/mellea_library.md @@ -1,5 +1,9 @@ # Mellea should be as close to a library as possible +> **Note.** This is a design-philosophy statement (library vs. framework), not +> an API reference, and it has not been re-verified line-by-line against the +> current codebase. See #1482 for the `docs/dev/` currency discussion. + We should make it possible to use mellea as a library (as opposed to a framework). In the context of LLM applications, the library vs framework distinction really boils down to how you treat the backend. diff --git a/docs/dev/mify.md b/docs/dev/mify.md index ab3af6e94..842361389 100644 --- a/docs/dev/mify.md +++ b/docs/dev/mify.md @@ -1,5 +1,13 @@ # mify +> **Status: outdated.** The code below does not run as written — `Circle` has no +> `__init__`, and `Customer.__init__` is missing its `self` parameter — and the +> implementation link points to `mellea/stdlib/mify.py`, which has moved to +> `mellea/stdlib/components/mify.py`. For accurate, working coverage of this +> topic, see [`docs/docs/concepts/mobjects-and-mify.md`](../docs/concepts/mobjects-and-mify.md) +> (published) or [`docs/examples/mify/mify.py`](../examples/mify/mify.py). See +> #1482 for the `docs/dev/` currency discussion. + In classical programming, object-orientation provides a way to couple data and functionality. Classes have fields and methods. Fields store data and methods operate over that data. diff --git a/docs/dev/spans.md b/docs/dev/spans.md index 28c19d3b9..6ea09946b 100644 --- a/docs/dev/spans.md +++ b/docs/dev/spans.md @@ -1,5 +1,13 @@ # Design Document for Spans +> **Status: unfinished stub.** This note breaks off mid-decision ("We need to +> document which approach we choose...") and no decision was ever recorded; no +> `SpanContext` or `__span_repr__` exists in the codebase. The `/dev/spans` URL +> on the published docs site now redirects to the unrelated OpenTelemetry +> tracing page ([`docs/docs/observability/tracing.md`](../docs/observability/tracing.md)), +> which does not cover this design. See #1482 for the `docs/dev/` currency +> discussion. + ## Span Contexts We will introduce a SpanContext which will behave kind of like a heap but with transformer-running-on-GPU memory primitives instead of malloc/realloc/free. The public interface to a SpanContext will roughly correspond to the sort of stuff you can do in Span algebras, if you've seen some of that work. diff --git a/docs/dev/tool_calling.md b/docs/dev/tool_calling.md index fff491d94..8a42bcbf2 100644 --- a/docs/dev/tool_calling.md +++ b/docs/dev/tool_calling.md @@ -1,5 +1,11 @@ # Tool Calling +> **Status: outdated.** The `SessionToolCallingProtocol` / `MelleaSessionToolProtocol` +> mixin proposed below (with `tool_call_result()` and `call_tool()`) was never +> implemented. The linked example, `docs/examples/agents/react/react_from_scratch/react.py`, +> uses its own `ReactTool` / `ReactToolbox` classes instead. See #1482 for the +> `docs/dev/` currency discussion. + ## Problem Statement Context management and execution of tool calls are inextricably linked, because most From 8304ff61f93e2dba6deb231cfe961e8f38dabb35 Mon Sep 17 00:00:00 2001 From: Nigel Jones Date: Fri, 31 Jul 2026 08:20:36 +0100 Subject: [PATCH 2/3] docs: add docs/dev/ guardrail to AGENTS.md AGENTS.md's directory structure table had no entry for docs/dev/ at all, so an agent had no way to learn from AGENTS.md that the directory exists or that its contents aren't maintained documentation. Add a row plus an explicit warning telling agents/contributors to check for a status banner and verify claims against source before relying on a docs/dev/ note. Assisted-by: Claude Code Signed-off-by: Nigel Jones --- AGENTS.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index fa606d778..d9f03a952 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -43,9 +43,21 @@ uv run mypy . # Type check | `cli/` | CLI commands (`m serve`, `m alora`, `m decompose`, `m eval`) | | `test/` | All tests (run from repo root) | | `docs/examples/` | Example code (run as tests via pytest) | +| `docs/dev/` | Internal design notes — **not verified documentation** | | `.agents/skills/` | Agent skills ([agentskills.io](https://agentskills.io) standard) | | `scratchpad/` | Experiments (git-ignored) | +⚠️ **`docs/dev/` is informal design notes, not maintained documentation.** Some +notes are current, some describe proposals that were never implemented or APIs +that have since changed, and some are unfinished stubs — nothing in the +directory is guaranteed accurate. Before relying on a claim from `docs/dev/` in +code, docs, or a review comment: check the top of the file for a status banner +(`outdated` / `unfinished stub` / `informal brainstorm`), and independently +verify the specific claim (class, method, signature, path) against current +source rather than trusting the note. See +[#1482](https://github.com/generative-computing/mellea/issues/1482) for the +ongoing discussion on a long-term currency policy for this directory. + ## 3. Test Markers Tests use a four-tier granularity system (`unit`, `integration`, `e2e`, `qualitative`) plus backend and resource markers. The `unit` marker is auto-applied by conftest — never write it explicitly. The `llm` marker is deprecated; use `e2e` instead. From b8eb6d34c34d168c4e697417469e1e9b35a56275 Mon Sep 17 00:00:00 2001 From: Nigel Jones Date: Fri, 31 Jul 2026 08:31:36 +0100 Subject: [PATCH 3/3] docs: fix stale mify.md links and constrained_decoding.md wording Follow-up from a self-review of the status banners added in this PR: - mify.md's own bottom-of-file links were still pointing at the old paths (examples/mify.py, stdlib/mify.py) even though the new banner above them gives the correct ones; fix them to match, and note the second example's undefined `c` (should be `customer`) in the banner. - constrained_decoding.md's banner said "unattributed suggestions" but the note actually names Hendrik/Nathan/Masataro; reworded to "informally paraphrased" to avoid the inaccurate claim. Assisted-by: Claude Code Signed-off-by: Nigel Jones --- docs/dev/constrained_decoding.md | 6 +++--- docs/dev/mify.md | 10 ++++++---- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/dev/constrained_decoding.md b/docs/dev/constrained_decoding.md index 2ef75078b..8cc0b8e4a 100644 --- a/docs/dev/constrained_decoding.md +++ b/docs/dev/constrained_decoding.md @@ -1,9 +1,9 @@ # Constrained Decoding > **Status: informal brainstorm.** This note records open questions and -> unattributed suggestions from an early discussion; no decision was ever -> recorded and nothing below should be treated as settled design. See #1482 -> for the `docs/dev/` currency discussion. +> informally paraphrased suggestions from an early discussion; no decision was +> ever recorded and nothing below should be treated as settled design. See +> #1482 for the `docs/dev/` currency discussion. ## How do constraints get defined? diff --git a/docs/dev/mify.md b/docs/dev/mify.md index 842361389..40f437a57 100644 --- a/docs/dev/mify.md +++ b/docs/dev/mify.md @@ -1,8 +1,10 @@ # mify > **Status: outdated.** The code below does not run as written — `Circle` has no -> `__init__`, and `Customer.__init__` is missing its `self` parameter — and the -> implementation link points to `mellea/stdlib/mify.py`, which has moved to +> `__init__`, `Customer.__init__` is missing its `self` parameter, and the +> second example calls `mify(c)` / `m.query(c, ...)` on an undefined `c` (it +> meant `customer`) — and the implementation link points to +> `mellea/stdlib/mify.py`, which has moved to > `mellea/stdlib/components/mify.py`. For accurate, working coverage of this > topic, see [`docs/docs/concepts/mobjects-and-mify.md`](../docs/concepts/mobjects-and-mify.md) > (published) or [`docs/examples/mify/mify.py`](../examples/mify/mify.py). See @@ -77,5 +79,5 @@ customer.execute("send an email.", email_body, email_subject) ``` For more examples and information, see -- [Mify Examples](../examples/mify.py) -- [Mify Implementation](../../mellea/stdlib/mify.py) +- [Mify Examples](../examples/mify/mify.py) +- [Mify Implementation](../../mellea/stdlib/components/mify.py)