research: define library, project and organ ecosystem roles

[Jammy2211]

Overview

Investigate whether explicit library, project/workspace and organ roles would improve agent context selection, ownership and routing. Use visualization as an existing case and profiling/inference as planned cross-project organs. The human approved the research plan and branch in-session on 2026-10-01; adopting the architecture remains a later decision.

Plan

• Compare library → project/workspace → organ with a relationship graph, including Nerves and other counterexamples.
• Map execution, artifacts, registries, dashboards, judgment and science records for visualization, profiling and inference.
• Demonstrate agent context selection and routing through three worked examples.
• Produce one cited design note, recommendations and staged follow-ups, distinct from adopted policy.

Detailed implementation plan

Affected Repositories

• PyAutoBrain (primary; design note only).
• Mind lifecycle bookkeeping. Eyes, profiling, inference and other relevant contracts are read-only evidence, not development claims.

Branch Survey

Repository	Current Branch	Dirty?
PyAutoBrain	main	clean
PyAutoMind	codex/ecosystem-layers-research	clean

No active PyAutoBrain claim conflict. autolens_inference is claimed by another task and will only be read.
Approved branch: feature/ecosystem-layers.
Worktree: /home/jammy/Code/PyAutoLabs/.worktrees/ecosystem-layers/PyAutoBrain.

Implementation Steps

1. Inspect ORGANISM.md, Mind repos.yaml, Eyes registry/manifest contracts and relevant project instructions. Consult Memory/history for prior decisions; distinguish current evidence from proposals and stale prose.
2. Write docs/research/ecosystem_levels.md as a non-normative design note, with source citations, vocabulary alternatives, an ownership table and a relationship diagram.
3. Walk through a visualization defect, profiling drift and inference benchmark finding, naming the evidence owner, context selection and existing action door at each stage.
4. Propose the smallest useful metadata/read-contract/routing changes and an ordered follow-up path for profiling and inference organs. Include no-change alternatives and unresolved human decisions. Do not change policy, registries, code, campaigns or create organs.
5. Check citations, Markdown structure, diagram consistency and the five prompt acceptance criteria. Run an applicable docs build if the existing environment supports it. Record any existing documentation drift separately.

Key Files

• docs/research/ecosystem_levels.md — sole research deliverable.
• ORGANISM.md — canonical policy evidence, unchanged.
• ../PyAutoMind/repos.yaml — repository identities, unchanged.
• ../PyAutoEyes/REFERENCE.md — project/organ read boundary evidence.

Validation and gates

Heart entry feed: STALE (test run status unknown/no report.json; install verification not run; no release validation for current source). Re-read readiness at shipping. No library APIs change, so scientific smoke campaigns are not applicable. Human merge remains separate.

Original Prompt

Starting prompt

Explore source, project/workspace, and organ levels in the agentic ecosystem

Type: research
Target: PyAutoBrain
Repos:

• autolens_inference
• autolens_profiling
• autolens_visualization
• PyAutoBrain
• PyAutoEyes
  Difficulty: medium
  Autonomy: supervised
  Priority: normal
  Status: formalised
  Consequence: judge
  Review-minutes: 20
  Unattended: ready

Original user request (verbatim)

In promoting autolens_visualization to PyAutoEyes, I used the term "workspace" level. I think this has important
contexts, we are now building up layers of the ecosystem where there is a source code level, workspace
level (which includes stuff like profiling) and the organ level. I think a prompt which explores this and
works out if it can be built into the agentic AI design may yield fruit. workspace level could also be
repo level, separate from the source code level.

Note also that I soon want to add a dashboard (and thus organ) for profiling (which pairs to autolens_profiling
and other _profiling repos) and for inference (which pairs to autolens_inference) and other inference repos.
These also feel like they help define the organ level, as they will have many repos at the repo or workspace level
which link to an organ and dashboard.

Research question

Investigate whether explicit ecosystem levels would improve agent context selection,
ownership, routing, and human oversight. Treat the proposed levels as a hypothesis
and recommend useful terminology and boundaries, including a simpler alternative
if a strict hierarchy does not fit. This is one bounded architecture investigation,
not implementation of new organs or dashboards.

Cases and questions

• Distinguish reusable source/library capabilities; project/workspace repositories
  that exercise them, run campaigns and produce evidence; and organs that own
  cross-project responsibilities, registries, durable state and human dashboards.
  Compare "workspace", "project", and "repo" for the middle level. Repositories
  and source code also exist at the other levels: separate packaging from role.
• Ground the proposal in visualization: library plotting code, the per-library
  visualization producers and artifacts, and Eyes' registry/dashboard. Check what
  was actually promoted or aggregated rather than assuming the producer disappeared.
• Work through planned profiling and inference organs, each connected to multiple
  corresponding project repos across libraries. Separate per-project run dashboards
  from cross-project organ dashboards. Keep proposed organ names undecided.
• Identify where scripts, manifests, results, provenance, freshness, judgments,
  execution and state belong. Examine Brain conductor/faculty responsibilities,
  Cortex science ledgers, Heart readiness and Mind intent to avoid duplicate owners.
  Compare the proposal with the existing rule that new organs require distinct
  state or effects; investigate when a dashboard warrants an organ.
• Decide whether relationships form a strict hierarchy or a graph: multiple
  projects per organ, possible multiple organ consumers per project, and organs
  such as Nerves that also provide library code. Do not force every organ into
  an evidence-aggregation template.
• Show how an agent would use the distinction: selecting minimal context, locating
  the authoritative owner, reading evidence, deciding the correct action scope,
  and routing a finding back to library or project work with provenance. Preserve
  existing development and human decision gates; do not assume a level requires
  its own LLM agent or extra delegation.

Evidence and related work

Start from Brain's ORGANISM.md and Mind's repos.yaml, then read only relevant
Eyes contracts and profiling/inference project instructions. Consult Memory for
prior architectural decisions before finalizing recommendations. Distinguish
verified current arrangements from planned capabilities.

Related existing task (Mind-relative):
draft/feature/pyautobrain/register_profiling_dashboard_on_brain_board.md.
That task registers a project profiling dashboard and explicitly excludes organ
birth. This research should complement it and identify dependencies, not repeat it.

Deliverable and acceptance criteria

Produce one cited design note with:

1. A recommended vocabulary, comparison of plausible alternatives, and explicit
   reasons for adopting or rejecting levels in the agentic design.
2. An ownership/relationship diagram and responsibility table, exercised against
   visualization, profiling and inference, including counterexamples and overlaps.
3. Concrete agent-routing examples: a visualization defect, profiling drift, and
   an inference benchmark finding, from evidence to the responsible next action.
4. A minimal proposal for any registry metadata, read contracts, agent instructions
   or routing changes, identifying canonical owners and avoiding parallel registries.
5. A staged follow-up recommendation for profiling/inference organs and general
   wiring, with dependencies, open human decisions, and a no-change option.

Do not create organs, run campaigns, change code or registries, or implement the
proposed design as part of this research task. The result should support a human
architecture decision before separately scoped implementation work.

[Jammy2211]

Research complete locally — shipping gate

The approved design note is ready in docs/research/ecosystem_levels.md on
feature/ecosystem-layers (base c7bfd68), worktree
/home/jammy/Code/PyAutoLabs/.worktrees/ecosystem-layers/PyAutoBrain.
It is not committed or pushed: the current Heart gate blocks those development-shipping actions.

Recommendation: use library/project/organ as responsibility roles, repositories as
packaging, and explicit relationships rather than a containment hierarchy. Trial
owner/evidence/action routing before adding metadata. Profiling/inference can have
separate cross-project organ contracts while project artifacts and Cortex science
records keep their existing owners. Policy and registries remain unchanged.

Validation: Sphinx HTML build passes with zero warnings (baseline zero); 28 citations
to 15 commit-pinned source files resolve locally; whitespace clean; all five prompt
acceptance criteria addressed. Author editorial review completed; independent faculty
review is not required by this ordinary, non-auto research path. Scientific smoke is
not applicable to this one-file prose change.

Local artifacts, relative to the task bundle: research-validation.txt,
sphinx-build.log, sphinx-warnings.log, docs-html/research/ecosystem_levels.html,
heart-readiness.json, and prepared research-pr.md.

Heart readiness (2026-10-01T17:10:05Z): RED. Exact reasons:

• release validation FAILED (stage integrate)
• workspace validation not passing (0 failed, 1 timeout, cloud#36404726969: autolens_test scripts/multi_dataset/rectangular.py)
• 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

Next action: obtain a live development-only Heart RED override for Brain #440 before
commit/push/PR. Record any grant in the four sinks required by AUTONOMY.md, re-check
current reasons, and open the research PR. Merge remains separate. No release or
readiness repair is claimed. No background waiter is armed.

[Jammy2211]

Fable review complete: CLEAN

Applied the independent review findings to docs/research/ecosystem_levels.md:

• Separate project manifest/GALLERY.md defects from Eyes dashboard URL/link defects.
• Record the Memory consultation disposition without exposing private source content.
• Distinguish the proposed project role from existing repository categories; preserve category-specific workflow/release gates.
• Clarify existing identity/layering precedents and scope of stale documentation copies.

Claude Fable 5.1 re-reviewed the final local draft and returned CLEAN. Exact
reviewed SHA256: 3345cd00f3354c428426ef87d9092ef7683ca570e5c3bb8941d1abc860ef9d0b.
This is an uncommitted local-draft review, not a committed-head gate.

Validation: Sphinx HTML succeeds with zero warnings; 32 citations to 17 pinned
source files verified; whitespace clean. Scientific smoke not applicable.
Task-bundle evidence: fable-final-review.md, fable-final-review-result.json,
research-validation.txt, sphinx-build.log, sphinx-warnings.log.

Development commit/push/PR remain held at Heart RED, exact RED reason:
release validation FAILED (stage integrate).
No Heart override inferred from the instruction to proceed with review fixes.
Next: live development-only override for this task, or a permitting Heart verdict;
then commit this reviewed artifact, push and open the prepared research PR.
Merge remains separate. No background monitor is armed.

[Jammy2211]

Human-authorized Heart RED override (development only)

The live user replied "yes do it", then "I authorize", to the explicit request:
"Authorize a development-only Heart RED override for #440 to commit, push and open the PR?"
This authorizes task ecosystem-layers, issue #440, branch feature/ecosystem-layers,
for commit, push and PR creation only. No merge, release, rehearsal or CI bypass.

Current Heart verdict: RED; re-read from readiness in this shipping turn,
snapshot 2026-10-01T17:10:05.266085+00:00. Exact RED reason:

• release validation FAILED (stage integrate)

Other current readiness reasons:

• workspace validation not passing (0 failed, 1 timeout, cloud#36404726969: autolens_test scripts/multi_dataset/rectangular.py)
• 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

Passed branch evidence: Sphinx HTML build with zero warnings (baseline zero);
32 citations to 17 commit-pinned source files verified; whitespace clean;
independent Claude Fable 5.1 final draft review CLEAN. Scientific smoke is not
applicable to this one-file research Markdown change. The reviewed SHA256 is
3345cd00f3354c428426ef87d9092ef7683ca570e5c3bb8941d1abc860ef9d0b and remains unchanged.
This is independent local-draft review evidence, not a claim that Fable reviewed
a committed branch head. The commit will contain that exact reviewed artifact.
Heart remains RED for release purposes; this note does not repair Heart.

[Jammy2211]

Research PR opened

PR: #441
Commit: 9ae0db90518cedf4de558e79ad291d5af587e435 on feature/ecosystem-layers.
Label pending-release verified. The committed Markdown matches the exact
SHA256 of the draft Claude Fable 5.1 marked CLEAN. Sphinx builds with zero warnings;
32 citations to 17 pinned source files checked. No executable changes.

Opened under the live development-only Heart RED override recorded above and in
the PR, Mind active entry and autonomy calibration log. Heart's exact RED reason
remains release validation FAILED (stage integrate); no repair/release claim.

Initial CI snapshot: pytest (3.12), pytest (3.13), and docs/docs-build in progress.
Mind status: awaiting-merge. No merge performed or authorized. Human /prm after
required checks are green; no background watcher is armed.

[Jammy2211]

Shipped

Merged research PR #441
as 9e4c8064d4f56bb34b0a73f45416126f4d15c616 under the human $prm instruction.
All 2 Actions runs / 3 jobs passed for feature head 9ae0db9; mergeability was CLEAN.
Independent Claude Fable review CLEAN; local docs build zero warnings; reviewed
artifact SHA matches the committed file. Development Heart override is recorded above;
this merge does not clear Heart or authorize a release.

The note explores library/project/organ responsibilities, preserves category-based
release gates, and proposes profiling/inference follow-ups. It is a design proposal,
not adopted policy. Mind completion record: complete/2026/10/ecosystem-layers.md.