docs: mark stale docs/dev/ design notes as outdated

[planetf1]

Pull Request

Issue

Ref #1482

Description

Related to #1482 — adds a short status banner to each docs/dev/ design note confirmed stale or unfinished during a source-level audit, so contributors and coding agents don't mistake it for current behaviour. No code changes; docs only.

Banners added:

• intrinsics_and_adapters.md — predates Epic Epic: Fix Adapter Function Lifecycle & Consistency in Mellea #929's capability-based adapter model; rewrite already tracked in refactor(intrinsics): remove deprecation shims; rewrite intrinsics_and_adapters.md; write 3 tutorials (Epic #929 Phase 4) #1144
• tool_calling.md — proposes a SessionToolCallingProtocol mixin that was never implemented; the shipped example (docs/examples/agents/react/react_from_scratch/react.py) uses unrelated ad hoc classes instead
• mify.md — example code doesn't run as written, and the implementation path it cites has moved; points readers to the published docs/docs/concepts/mobjects-and-mify.md and the working example
• spans.md — unfinished stub, breaks off mid-decision; no SpanContext exists in the codebase; notes that the old /dev/spans redirect now points to an unrelated OpenTelemetry tracing page
• constrained_decoding.md — informal brainstorm with no recorded decision
• mellea_library.md — philosophy statement, not re-verified line-by-line against current code

generate_ctx_signature.md, hook_system.md, and requirement_aLoRA_rerouting.md were checked against source and left unchanged — they still match current code.

Also adds a docs/dev/ row to AGENTS.md's directory structure table, plus a guardrail telling agents/contributors to check for a status banner and verify claims against source before relying on a note from this directory — AGENTS.md previously didn't mention docs/dev/ at all, so there was no way to learn from it that the directory exists or that its contents aren't maintained documentation.

This is a starting point for the discussion in #1482, not a final policy. Opening as a draft since #1482 is still open for discussion on the right long-term approach (banners vs. archiving vs. folding into published docs, etc.) — happy to adjust scope based on how that lands.

Testing

• Tests added to the respective file if code was changed
• New code has 100% coverage if code was added
• Ensure existing tests and github automation passes (a maintainer will kick off the github automation when the rest of the PR is populated)

Attribution

• AI coding assistants used

---

Adding a new component, requirement, sampling strategy, or tool?

If your PR adds or modifies one of the types below, check the matching box. A checklist of type-specific review items will be posted as a comment.

• Component
• Requirement
• Sampling Strategy
• Tool

NOTE: Please ensure you have an issue that has been acknowledged by a core contributor and routed you to open a pull request against this repository. Otherwise, please open an issue before continuing with this pull request.

[planetf1]

cc @ajbozarth — following up on our discussion about the OTel-on-adapters mis-step (#1464): the root cause there was a stale docs/dev/ note that didn't reflect the hook-fired plugin architecture, so this PR (and the open discussion in #1482) is a direct response — status banners on the notes confirmed stale/unfinished, plus a guardrail in AGENTS.md telling agents/contributors to verify docs/dev/ claims against source rather than trust them outright.

[ajbozarth]

This feels a bit more like a bandaid, I think the better solution would be cleaning up old unneeded docs and investigating the good docs for a potential move actual docs. Either way the AGENTS update is probably good.

We could also both clean it up and potentially reframe the dir's intent to be docs mean for AI consumption not public and then keep them up to data and keep pitches/plans out of that dir. No matter what I think we need to decide as a team what the intent of docs/dev/ is.

[planetf1]

@ajbozarth Yes it is a quick workaround -- the principle being to do something to address the urgent/immediate problem (which hurt us on a design recently). I didn't make it clear or raise a specific followup on the content - and you're right this is needed.

So I still think it's worth making this change as a minimal, quick fix which shouldn't have side-effectts or impacts on human readers and then have a longer term fix (perhaps one issue per document - which is actually what claude suggested when I originally was analyzing?). This also allows that work to be done in parallel, by the different owners of the different content?

Does that make sense?

[markstur]

I didn't submit my review earlier because it was mostly agreeing with Alex and some rambling..., but

1. Agree that it would be good to purge outdated design docs or archive somewhere and keep the accurate details in actual maintained docs and readmes.
2. I'd add that this is a good triage effort to help make sense of the current stuff for now
3. This has the important part about explaining to agents how to use/not-use design docs, which is important if we continue to keep or create them in the future.

I approve, but am watching for @ajbozarth to approve or block.

[psschwei]

@ajbozarth Yes it is a quick workaround -- the principle being to do something to address the urgent/immediate problem (which hurt us on a design recently). I didn't make it clear or raise a specific followup on the content - and you're right this is needed.

So I still think it's worth making this change as a minimal, quick fix which shouldn't have side-effectts or impacts on human readers and then have a longer term fix (perhaps one issue per document - which is actually what claude suggested when I originally was analyzing?). This also allows that work to be done in parallel, by the different owners of the different content?

Does that make sense?

This doesn't strike me as something that's urgent. If we're going to fix it, may as well fix it right rather than piecemeal. For the time being, could just ignore docs/dev/ on prompts, add a memory (or claude.md) that they're out of date, etc.

[ajbozarth]

So I still think it's worth making this change as a minimal, quick fix

This is fair, and I won't block this, but I still think that just fixing it is the better solution