docs: adopt library, project and organ responsibility roles

[Jammy2211]

Overview

Adopt the library/project/organ responsibility vocabulary accepted after research #440 / PR #441. Reconcile Brain's canonical and public descriptions with the existing Eyes project/organ boundary, while preserving repository categories and their workflow/release contracts.

Human approval: "contiue and i approve" to the explicit implementation plan and branch feature/ecosystem-role-docs, 2026-10-01.

Plan

• Define library, project and organ responsibilities in the canonical organism description.
• Correct Eyes ownership: project repos render/store figures; Eyes reads manifests and presents the cross-project dashboard; Brain judges.
• Reconcile public docs and distinguish responsibility roles from repository categories.
• Build Sphinx, verify links and source-of-truth consistency, and obtain independent review.

Detailed implementation plan

Affected Repositories

PyAutoBrain only; Mind lifecycle bookkeeping. Inference documentation is separately filed and blocked by an existing claim.

Branch Survey

PyAutoBrain: main, clean; no active claim conflict.
Approved branch: feature/ecosystem-role-docs.
Worktree: /home/jammy/Code/PyAutoLabs/.worktrees/ecosystem-role-docs/PyAutoBrain.

Implementation Steps

1. Edit ORGANISM.md first: add role vocabulary and non-containment relationships, acknowledge Nerves' overlapping organ/library responsibilities, and correct the Eyes row/growth example.
2. Update docs/concepts/organism.md, including stale rendering ownership and framework/instance wording; link canonical definitions.
3. Add a concise role/category distinction and canonical link to docs/satellites.md; retain all category-based release rules.
4. Inspect docs/organs/eyes.md and related Brain docs for contradictions. Change only required boundary text. Preserve the dated research note's pinned historical observations.
5. Validate links/anchors and Sphinx with zero warning regression; independent review of the final diff. Scientific smoke not applicable to prose-only changes.

No code, schema, registry, new-agent or organ-birth changes. Generated maps already carry the correct Eyes row; no generated block hand edits. No adoption of routing trials or profiling/inference organ implementation. Existing RTD currency task remains separate.

Heart entry feed: STALE (test report absent, install verification not run, no release validation for current source). Re-evaluate at shipping; previous task #440's override does not authorize this task.

Original Prompt

Starting prompt

Adopt ecosystem responsibility roles and reconcile Brain documentation

Type: docs
Target: @PyAutoBrain
Repos:

• PyAutoBrain
  Difficulty: small
  Autonomy: supervised
  Priority: normal
  Consequence: judge
  Filed: 2026-10-01
  Status: draft

Original user request (verbatim)

continue

User's selected continuation (verbatim)

Adopt the terminology and reconcile existing documentation (recommended)

Context and accepted direction

Follow the research merged in PyAutoBrain#441 (issue #440), documented in
docs/research/ecosystem_levels.md; Mind completion record
complete/2026/10/ecosystem-layers.md. The human selected adopting the terminology
and reconciling existing documentation. This accepts library/project/organ as
responsibility roles; repository remains packaging. Existing repository categories
and their validation/release contracts remain authoritative and unchanged.

Scope

1. Update ORGANISM.md first: define the roles and relationships, account for
   Nerves as both organ and library package, and correct Eyes' row and growth
   example to the current project-manifest/dashboard split. Project repos own
   render harnesses and figure artifacts; Eyes owns registry/read contract and
   dashboard; the Brain conductor judges.
2. Reconcile docs/concepts/organism.md with that canonical definition, including
   the stale Eyes table and framework/instance prose about rendered figures.
   Link to the canonical owner rather than inventing parallel policy.
3. Add a concise distinction in docs/satellites.md: responsibility role is not
   a body-map category, not a category: project filter, and not a change to
   workspace release gates. Link the role definition.
4. Check docs/organs/eyes.md and relevant Brain docs for contradictions; change
   only text needed to reconcile these boundaries. Keep the dated research note
   as the historical proposal rather than rewriting its pinned observations.
5. Build Sphinx with no warning regression and check links/source-of-truth
   consistency. Review the adoption wording independently before shipping.

Boundaries and related work

No code/schema/registry changes, repository renames, new agents, new organs or
new dashboards. Agent routing trials and profiling/inference organ specifications
remain later tasks. Existing generated map rows already describe the correct Eyes
split; use the generator if a generated surface actually needs changing, and report
any expansion in affected repos before proceeding.

draft/docs/pyautobrain/rtd_organism_currency.md covers a Nerves page, count drift
and the build/hands URL decision; leave those unrelated changes and its prompt intact.
Stale Cortex references in inference are a separate follow-up:
draft/docs/autolens_inference/reconcile_cortex_ledger_references.md.
That repo is currently claimed by point-source-search-nautilus-leaf; do not edit it
or take its claim for this Brain-only task.

Acceptance

The canonical definition and public docs agree on the three roles, explicitly
preserve categories/release semantics, and describe Eyes consistently with its
current read contract. Sphinx warning baseline remains zero. No implication that
profiling/inference organs already exist or that the routing trial has been adopted.

[Jammy2211]

Documentation complete locally — independent review CLEAN

Approved plan implemented in five Markdown files on feature/ecosystem-role-docs,
base 9e4c806, worktree /home/jammy/Code/PyAutoLabs/.worktrees/ecosystem-role-docs/PyAutoBrain:

• ORGANISM.md: canonical responsibility vocabulary, non-containment relationships,
  role/category separation, and correct Eyes ownership/growth example.
• docs/concepts/organism.md: aligned summary, canonical link and instance wording.
• docs/satellites.md: responsibility roles distinguished from category contracts.
• docs/organs/eyes.md: corrected adopter/ownership wording.
• skills/eyes/eyes.md: stale boundary clause corrected after independent review;
  commands and workflow unchanged. This is scope item 4's factual reconciliation,
  not adoption of a routing trial or new agent behavior.

Validation: Sphinx HTML PASS, zero warnings (baseline 0); link/anchor checks and
whitespace PASS. Independent Claude Fable 5.1 final review CLEAN. Working-tree
hashes in task-bundle review-final-hashes.json match all five reviewed files.
No executable/schema/registry/inference changes; research note unchanged.
Scientific smoke N/A. No committed-head review claim.

Heart's current shipping verdict is YELLOW (snapshot 2026-10-01T19:19:38.640864+00:00). Exact reasons:

• manifest drift: public front-door organ tables (generated) — 1 mismatch(es) vs PyAutoMind/repos.yaml
• manifest drift: workspace checkouts (manifest ↔ disk) — 1 mismatch(es) vs PyAutoMind/repos.yaml

No RED reasons remain. Need live acknowledgement of these YELLOW reasons before
commit/push/PR for #442. The prior #440 override does not apply to this task.
Next: acknowledge, commit exact reviewed files, push, open prepared PR; merge
separate. Mind status awaiting-input. No background monitoring.

Evidence in task bundle: validation.txt, fable-final-review.md,
fable-rereview-result.json, sphinx-build.log, sphinx-warnings.log,
heart-readiness.json, review-final-hashes.json, research-pr.md.

[Jammy2211]

Shipping gate cleared

Heart updated to GREEN, score 100, no remaining reasons, snapshot 2026-10-01T19:24:04.745228+00:00.
The earlier YELLOW checkpoint is superseded; no override or acknowledgement is needed.
All five files still match the exact hashes independently reviewed CLEAN by Claude
Fable 5.1. Proceeding with commit/push/PR under the approved development plan.
Merge remains a separate human action.

[Jammy2211]

Documentation PR opened

#443
Commit 6a124d9 on feature/ecosystem-role-docs; pending-release label verified.
All five committed files match the exact independent Claude Fable 5.1 CLEAN
working-tree review hashes. Sphinx build zero warnings; links/whitespace PASS.
Heart GREEN at shipping, score 100, no reasons (2026-10-01T19:24:04.745228+00:00).
Earlier YELLOW checkpoint superseded; no override used for this task.

Mind awaiting-merge. CI is running; no merge performed or authorized. Human /prm
when required checks are green. Inference Cortex documentation remains a separately
filed task, not part of this PR. No background waiter is armed.

[Jammy2211]

Shipped

Merged #443 as
0f7831b8a73641bb0add82ac3ed02d2edf565153 under the human $prm instruction.
Both Actions runs and all three jobs passed at feature head 6a124d9;
mergeability was CLEAN. Fable review CLEAN; Sphinx zero warnings; Heart GREEN
at shipping. No override, release or rehearsal.

Canonical/public docs now agree on library/project/organ responsibilities and
Eyes production/aggregation/judgment boundaries. Category/release rules and
runtime behavior remain unchanged. Inference documentation is separately filed.

Mind record: complete/2026/10/ecosystem-role-docs.md. Review evidence retained
before worktree cleanup.