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.