Add capture-before-act rule for user-supplied reference materials

[EsatanGW]

Summary

Adds a new operating-contract rule (AGENTS.md §11) mandating that external reference materials provided by users during a change (design files, prototype links, requirement documents, PDFs, screenshots, transcripts, or any URL/file the change must conform to) are persisted to project memory before implementation begins, rather than held only in conversation scrollback. This closes a recurring failure mode where downstream sessions "ignore the design" because the original reference was lost to context compression or session break.

Scope classification

• Full — multiple surfaces, new contract, public behavior change

Surfaces touched

• System-interface surface (new operating-contract rule defining mandatory capture protocol and forbidden patterns)
• Information surface (new discipline-level rule with specific capture requirements and cross-references)

Rationale:

• System-interface: AGENTS.md §11 is a new normative rule in the operating contract that all AI agents must follow; it defines preconditions (capture before act) and forbidden patterns.
• Information surface: docs/ai-project-memory.md §User-supplied reference materials defines the mandatory capture protocol, rationale, forbidden patterns, and relationships to other rules; CHANGELOG entries document the new requirement.

Source of Truth impact

• SoT files: docs/ai-project-memory.md (new section §User-supplied reference materials — the canonical source of truth for capture protocol, forbidden patterns, and rationale)
• Consumer updates in this PR:
  • AGENTS.md §11 (operating-contract summary pointing to SoT)
  • CHANGELOG.md (Added section documenting the new rule)
  • CHANGELOG.json (structured changelog entry)
• Known consumers NOT updated and why:
  • Thin-bridge files (CLAUDE.md, GEMINI.md, .windsurfrules, .cursor/rules/*.mdc, agents/*.md) inherit automatically per docs/file-role-map.md and carry no new normative content; they are not updated in this PR.

Evidence

The change is purely documentation/contract definition:

• docs/ai-project-memory.md now contains a new section (lines 152–191) titled "User-supplied reference materials" with:

  • Definition of the problem (external references as a subclass of memory-worthy content)
  • Mandatory capture protocol (4 steps for URL-based, file-based, inline intent, and citation)
  • Rationale (why this is discipline-level)
  • Forbidden patterns (4 anti-patterns explicitly named)
  • Relationship to other rules (cross-references to AGENTS.md, ai-operating-contract.md, multi-agent-handoff.md)

• AGENTS.md §11 (new section after §10) contains:

  • Operating-contract summary of the rule
  • Mandatory capture steps (URL-based, file-based, inline intent, citation)
  • Forbidden patterns (inline)
  • Severity statement (same as §1 non-fabrication rules)
  • Link to SoT in docs/ai-project-memory.md

• CHANGELOG.md and CHANGELOG.json both document the addition under "Added" with full context and cross-references.

No automated tests apply (this is a contract/discipline rule, not code). The change is self-contained and ready for review.

Breaking-change level

• L0 — additive, no consumer action required.

This is a new rule that applies prospectively to future sessions. Existing sessions and completed work are not affected. Agents adopting this repo will inherit the rule through AGENTS.md and the referenced SoT.

Rollback mode

• Mode 1 — reversible by revert (documentation change).

Cross-cutting concerns

• Testability — no new CI jobs or validator coverage added; this is a contract rule, not executable code.

Checklist before requesting review

• Scope matches the intent: new operating-contract rule for reference-material capture.
• No drive-by refactors; all changes are scoped to the new rule and its documentation.
• [

https://claude.ai/code/session_01TkDVaswMTWwzwQjxUSzsve