PyAutoScientist Phase 1: licences, READMEs, Build hygiene, tenant firewall

[Jammy2211]

Overview

Phase 1 of the PyAutoScientist generalisation: make the five organ repos (Brain, Mind, Heart, Memory, Build) legally adoptable and presentable without touching any behaviour surface. Scoping is settled in PyAutoMind/docs/pyautobrain/pyautoscientist_generalisation_assessment.md (§1 coupling audit, §8 config-diff-fork adoption model) — do not re-litigate. Phases 2 (PyAutoScientist RTD) and 3 (demand-gated config extraction) are explicitly not part of this issue; the prompt in issued/ remains their anchor.

Plan

• Add MIT LICENSE (Copyright (c) 2026 Jammy2211) to PyAutoBrain, PyAutoMind, PyAutoHeart; PyAutoMemory gets MIT for scripts/structure + CC-BY 4.0 for wiki content (human-decided in-session).
• Rewrite all five organ READMEs to ~20–40 human-written lines (what it is, one table/diagram, link to ORGANISM.md); kill the AI-essay style. READMEs are human-facing only.
• PyAutoMind's README is agent-load-bearing: relocate registry schemas / prompt taxonomy / "Prompt file format" sections verbatim to PyAutoMind/REFERENCE.md; the short README links to it; agent pointers (WORKFLOW.md, Brain conductors, Heart pyauto-status) stay untouched and resolve via one extra hop.
• PyAutoBuild hygiene: test_results/ is already gitignored + untracked (the assessment's "committed" claim is stale on that half); evacuate the committed 4-line to_do_list file (content → a PyAutoMind note) and gitignore it.
• Extend PyAutoMind/scripts/repos_sync.py --check with a tenant-firewall check: no manifest-derived instance fact (repo names, owners PyAutoLabs/Jammy2211, workspace paths) in Brain/Heart/Build *.py/*.sh outside an allowlist of declared config surfaces seeded from the assessment §1 inventory. Must be green on current mains before ship.

Detailed implementation plan

Affected Repositories

• PyAutoBrain (primary)
• PyAutoMind
• PyAutoHeart
• PyAutoMemory
• PyAutoBuild

Branch Survey (2026-07-10)

Repository	Current Branch	Dirty?
./PyAutoBrain	main	clean
./PyAutoMind	main	clean
./PyAutoHeart	main	clean
./PyAutoMemory	main	clean (unrelated reading-queue.md mod, untouched)
./PyAutoBuild	main	clean

Suggested branch: feature/pyautoscientist-phase1 (worktree ~/Code/PyAutoLabs-wt/pyautoscientist-phase1/); no worktree claims conflict. One PR per repo → 5 PRs.

Implementation Steps

1. PyAutoBrain — LICENSE (MIT, (c) 2026 Jammy2211, matching PyAutoLens's style); README.md 130 → ~30 lines.
2. PyAutoMind — LICENSE (MIT); README.md 507 → ~30 lines + new REFERENCE.md holding the verbatim-moved schema sections; scripts/repos_sync.py: new check_tenant_firewall(root, repos) added to the checks dict — scans PyAutoBrain/PyAutoHeart/PyAutoBuild *.py/*.sh (excluding skills/*.md, AGENTS.md, docs) for instance facts derived from repos.yaml (repo names, owners, ~/Code/PyAutoLabs paths). Allowlist seeded from assessment §1 (all paths verified live):
   • PyAutoBrain: agents/faculties/sizing/_sizing.py, agents/conductors/intake/_intake.py, feature/refactor/release conductor constant tables, agents/conductors/release/nightly.sh
   • PyAutoHeart: config/repos.yaml, heart/readiness.py, heart/checks/version_skew.py, heart/checks/url_check_live.py + .sh
   • PyAutoBuild: pre_build.sh, autobuild/run_all.py, autobuild/slow_skip_check.py
   • Test fixtures allowlisted per-file as found during bring-up.
3. PyAutoHeart — LICENSE (MIT); README.md 325 → ~30 lines.
4. PyAutoMemory — LICENSE (MIT for scripts/structure + CC-BY 4.0 for wiki content, dual-licence file); README.md 82 → ~25 lines.
5. PyAutoBuild — README.md 56 → ~25 lines; git rm to_do_list (4 stale lines evacuated to a PyAutoMind note); .gitignore += to_do_list. (LICENSE already present.)

Key Files

• PyAutoMind/scripts/repos_sync.py — the only code change: additive check_tenant_firewall
• PyAuto{Brain,Mind,Heart,Memory}/LICENSE — new
• PyAuto{Brain,Mind,Heart,Memory,Build}/README.md — rewritten, human-facing only
• PyAutoMind/REFERENCE.md — new, verbatim relocation of agent-load-bearing README sections
• PyAutoBuild/.gitignore, PyAutoBuild/to_do_list — hygiene

Acceptance

• Zero diffs to skill bodies, AGENTS.md files, hooks, or organ runtime code (except the additive firewall check + Build gitignore).
• repos_sync.py --check green, including the new firewall check.
• One PR per repo, normal ship gate (supervised — present-and-wait at every checkpoint).
• Phase 2 (RTD) and Phase 3 explicitly NOT started.

Original Prompt

Click to expand starting prompt

Generalise the organism into PyAutoScientist: adoption assessment + unified docs

Type: docs
Target: PyAutoBrain
Repos:

• PyAutoBrain
• PyAutoMind
• PyAutoMemory
• PyAutoBuild
• PyAutoHeart
• PyAutoLens
• autolens_workspace
  Difficulty: too-large
  Autonomy: supervised
  Priority: normal
  Status: formalised

Make the PyAuto organism adoptable as PyAutoScientist — the basis for
other people's AI dev workflows, driving projects completely independent of
PyAutoFit/PyAutoLens — without splitting off from the repos in daily use and
without touching the live setup's behaviour.

The scoping is done: see the companion
pyautoscientist_generalisation_assessment.md (same folder) for the coupling
audit (§1), the category-contract insight (§2), the adversarial pass (§7) and
the settled adoption model (§8). This prompt is the execution order.

Settled direction (do not re-litigate at start_dev)

• Adoption model: config-diff fork (§8). One upstream — the live organs.
  Adopters fork Brain/Heart/Build, replace only the declared config surfaces,
  write their own Mind/Memory from skeletons, and git pull upstream cleanly.
  Never one shared deployment; never a second hand-maintained "generic"
  organism.
• One live organism. No genericisation of skills/*.md bodies (they are
  production prompts symlinked into ~/.claude), no AGENTS.md rewrites, no
  stability promises on organ main branches.
• Docs model (§4): one ReadTheDocs project pyautoscientist, sourced
  from PyAutoBrain/docs/ (growth rule: no new organs). The live lensing
  stack stays in the docs as the labelled worked example — do not purge it.

Phase 1 — zero behaviour risk (start here tomorrow)

1. Licenses. Add LICENSE to PyAutoBrain, PyAutoMind, PyAutoHeart,
   PyAutoMemory (PyAutoBuild already has one). Match the existing PyAuto
   library licence unless Jammy says otherwise; for PyAutoMemory decide
   structure-vs-content licensing explicitly (ask — human decision).
2. README rewrites. Shrink all five organ READMEs to ~20–40 human-written
   lines each: what it is, one table or diagram, link to ORGANISM.md and (once
   live) the RTD. READMEs are human-facing only — agents load AGENTS.md and
   skills — so this cannot regress behaviour. Kill the AI-essay style.
3. Build repo hygiene. Gitignore + evacuate PyAutoBuild/test_results/
   and to_do_list/ (committed instance run-state; collides with any fork's
   own runs).
4. Tenant firewall. Extend PyAutoMind/scripts/repos_sync.py --check
   with a check that no instance fact (repo name, owner, workspace path)
   appears in organ code outside the declared config surfaces (Heart
   config/repos.yaml, pre_build.sh tables, Brain constant tables in
   agents/*/_*.py, generated doc blocks). Seed the allowlist from the
   assessment §1 inventory. This protects the clean-pull property as the
   organs churn, and is drift hygiene for the live system regardless.

Phase 2 — the PyAutoScientist ReadTheDocs

5. RTD skeleton in PyAutoBrain/docs/ published as pyautoscientist:
   concepts (organism, organs, call chain, conductors/faculties, growth
   rule — sourced from ORGANISM.md, not duplicating it), per-organ reference,
   the category contract (what each satellite kind — library / workspace /
   workspace_test / howto / assistant — is for and what the organism expects
   of it), and the worked example (the live lensing instance, labelled as
   such). All new prose; it documents the skills, it never rewrites them.
6. Adoption guide written against the fork model: fork the organs →
   replace the config surfaces → write your body map → repos_sync --write
   → go. State the prerequisites plainly (Claude Code + ~/.claude skills,
   gh CLI, worktree layout, GitHub Actions/PyPI) as what PyAutoScientist
   is, not apologetically.
7. CONTRIBUTING + stability disclaimer in each organ: living reference
   implementation, main moves fast, copy/fork-and-pull, no compatibility
   promises. Hub card on pyautolabs.github.io linking the RTD.

Phase 3 — demand-gated

Trigger: a concrete adopter exists or a launch is committed (paper /
announcement / deliberate user-acquisition push). If the trigger is a launch,
do not go straight to publishing: recruit 1–3 friendly beta adopters after
Phase 2 and let their friction shape this phase — they are also the paper's
case studies, and they prove the adoption path end-to-end before strangers
try it. A launch additionally needs a turnkey quickstart on top of the items
below (an init bootstrap: zero → running organism in ~an hour).

• Config extraction: Heart version_skew/readiness/URL rules → config/;
  Build tables → policy YAML; Brain constant tables → derived from
  repos.yaml where identity, policy file where vocabulary.
• repos_sync --write stamping the organ config surfaces from the body map
  (turns "edit five mirrors" into "edit one file, regenerate" — also removes
  the live system's own hand-mirroring burden, so it may be pulled forward on
  its own merits).
• Mind/Memory skeletons (*-template, generated not hand-maintained) and an
  optional cookiecutter for the satellite pattern.

Acceptance for phases 1–2

• Zero diffs to skill bodies, AGENTS.md files, hooks, or organ runtime code
  (except the additive firewall check and Build gitignore).
• repos_sync.py --check green, including the new firewall check.
• Heart/Build/Brain test suites green; one PR per repo, normal ship gate.
• A stranger reading pyautoscientist RTD can explain the organism and knows
  exactly what forking it entails — without opening a single organ README
  essay.

Original request (verbatim)

PyAutoBrain, PyAutoMind, PyAutoMemory, PyAutoBuild (soon to be Hands) and PyAutoHeart make up an AI development ecosystem resembling a organism or a PyAutoScientist. some aspects of these repos might be specific to my workflow, how I develop PyAutoLens and over domain specific aspects of what I do. furthermore they are not documented and their GitHub repos Readme.md are long text and very AI written. could you do an assessment of how we generalise these repos so other people can adopt the PyAutoScientist AI agentic dev workflow and maybe put together docs for all repos (but just one readthedocs maybe called PyAutoScientist). Happy for your opinion on if thus can become a standalone open source repo others user can come in and if this can be done without splitting off from the repos I use also not that the design of domain specific things like PyAutoLens, autolens_workspace, autolens_assistqnt and the test and HowTo things are built into the PyAuto design so even these may need to be Generalised? (e.g. an example PyAutoProject, autoproject_workspace and so on)

[Jammy2211]

Phase 1 shipped — 5 PRs open, one per organ:

Repo	PR	Contents
PyAutoBrain	#66	MIT LICENSE + 33-line README
PyAutoMind	#44	tenant firewall in repos_sync.py + LICENSE + README→REFERENCE.md split
PyAutoHeart	#49	MIT LICENSE + ~30-line README (health board block preserved)
PyAutoMemory	#17	MIT structure + CC-BY 4.0 content LICENSE + 31-line README
PyAutoBuild	#131	26-line README + to_do_list evacuated to Mind ideas.md + gitignored

Validation: Brain 8 / Heart 244 / Build 78 tests pass; repos_sync.py --check green from both roots including the new firewall (negative-tested both firing modes). Heart YELLOW (6 pre-existing reasons, none touched by this set) acknowledged in-session.

Noteworthy: the firewall bring-up scan found instance facts in 72 organ code files — much broader than the §1 headline tables — so the allowlist freezes the current per-file token baseline rather than listing only §1 files (a green check any other way needs Phase-3 config extraction). New facts in listed files and any fact in new files now fail --check.

Phases 2 (RTD) + 3 not started, per scope. Prompt anchor: PyAutoMind/issued/pyautoscientist_generalisation.md.

[Jammy2211]

All 5 Phase 1 PRs merged 2026-07-10 (Brain#66, Mind#44, Heart#49, Memory#17, Build#131). repos_sync.py --check green on the merged mains, tenant firewall active. Phases 2 (PyAutoScientist RTD) and 3 (demand-gated config extraction) remain anchored in PyAutoMind/issued/pyautoscientist_generalisation.md and will get their own issues when started. Closing.