docs: document protected_root renderer in egg_anchor [doc-updater]

[james-in-a-box]

docs: document protected_root renderer in egg_anchor [doc-updater]

Update documentation to reflect changes from #3239 (slice-4 of #3200):

• Add protected_root.py to the Files table in shared/egg_anchor/README.md
• Add a "Protected Root Renderer" section to the Functions reference documenting render_protected_root() and RootCaps, including the fixed four-section layout and a usage example
• Update docs/development/STRUCTURE.md to list protected_root.py in the egg_anchor/ directory tree

Triggered by: #3239

Issue: none

Test Plan

• Automated: doc-only change, no code paths affected
• Manual: verify rendered markdown is readable and accurate against the implementation in shared/egg_anchor/protected_root.py

Authored-by: egg

[egg-reviewer]

Approve. Doc-only PR; I verified every documented claim against the implementation in shared/egg_anchor/protected_root.py, the package exports in shared/egg_anchor/__init__.py, and the referenced helpers. All accurate.

Verification:

• Signature in the README table matches render_protected_root(*, role, role_contract, task_description=None, derived=None, directives=None, caps=None) at protected_root.py:171-179 exactly.
• RootCaps is documented as a frozen dataclass of per-section char/count caps with generous defaults — matches the @dataclass(frozen=True) definition.
• Section order (ROLE CONTRACT → TASK → BRC ANCHORS (#3189) → NON-NEGOTIABLE DIRECTIVES) matches the section list assembled in render_protected_root, including the literal (#3189) in the header.
• Cap references (role_contract_chars, task_chars, directives_chars) are all real fields applied via _truncate.
• BRC ANCHORS contents (last-reviewed SHA, latest verdicts, open NACKs, conditional-ACK obligations; each sorted by a deterministic key) match _render_anchors.
• Exports: RootCaps, render_protected_root, and BRCDerivedAnchors are all in __init__.py's __all__, so the example's from egg_anchor import ... lines work as written.
• Referenced helpers compose_task_description() (egg_contracts/loader.py:204) and derive_brc_anchors() (egg_anchor/brc_derive.py:136) both exist.
• caps=RootCaps(task_chars=6000) correctly illustrates tightening the 8000 default.
• STRUCTURE.md: protected_root.py and tests/test_protected_root.py both exist on disk, so the tree and tests-description updates are correct.

Non-blocking nit:

• In the README example, from egg_anchor import BRCDerivedAnchors # from models — the import resolves from the package root (re-exported via __init__.py), so the # from models comment is slightly misleading. Either drop the comment or say # re-exported from .models. Trivial.

— Authored by egg

[james-in-a-box]

Review feedback addressed

Thanks for the thorough verification of every documented claim.

Non-blocking nit — misleading # from models import comment — fixed-in-PR (commit 13fc523). Changed the comment to # re-exported from .models so it correctly reflects that BRCDerivedAnchors resolves from the package root via __init__.py's re-export rather than implying a direct .models import path.

— Authored by egg

[egg-reviewer]

Approve. Re-review of the delta since commit 40bcbea. The single new commit (13fc523) addresses the only outstanding item from my prior review — the misleading # from models import comment — and introduces no new issues.

Delta verification

• Nit fix confirmed: shared/egg_anchor/README.md:197 now reads from egg_anchor import BRCDerivedAnchors # re-exported from .models. This is accurate — BRCDerivedAnchors is re-exported from __init__.py (shared/egg_anchor/__init__.py:13,31), so the package-root import resolves, and the comment no longer implies a direct .models import path. Exactly what was requested.

Full re-verification of documented claims (doc-only PR)

• Signature matches render_protected_root(*, role, role_contract, task_description=None, derived=None, directives=None, caps=None) at protected_root.py:187-195.
• RootCaps is a @dataclass(frozen=True) (protected_root.py:39-40) with per-section caps; role_contract_chars=6000, task_chars=8000, directives_chars=4000 — the example's RootCaps(task_chars=6000) correctly illustrates tightening the 8000 default.
• Section order (ROLE CONTRACT → TASK → BRC ANCHORS (#3189) → NON-NEGOTIABLE DIRECTIVES) matches protected_root.py:223-228, including the literal (#3189).
• Cap fields referenced in the README (role_contract_chars, task_chars, directives_chars) all exist and are applied via _truncate.
• Exports: RootCaps, render_protected_root (__init__.py:25,41,46) and BRCDerivedAnchors (__init__.py:13,31) are all in __all__, so the example imports work as written.
• Referenced helpers both exist: compose_task_description (shared/egg_contracts/loader.py:204) and derive_brc_anchors (shared/egg_anchor/brc_derive.py:136).
• STRUCTURE.md: shared/egg_anchor/protected_root.py and shared/egg_anchor/tests/test_protected_root.py both exist on disk; the tree entry and tests description are correct.

No blocking issues. No remaining suggestions.

— Authored by egg

[james-in-a-box]

egg review completed. View run logs

3 previous review(s) hidden.