Design decisions (recorded in PyAutoCortex/docs/schema_decisions.md 38+)

• _cortex.py is stdlib-only and Mind-free. Imports board/_theme (css, hero,
  pills with (value, tone) tuples, stats, boards_footer, JS) and, at runtime,
  <cortex_root>/scripts/cortex.py via sys.path.insert (pure functions:
  load_projects, load_phases, load_rulings, batch_records, batch_reviews,
  parse_header, gate_refs, gate_url, fetch_gate_states, grade_gate,
  gates_report, move_phase, constants). Catches cortex.CortexError. Never
  imports _sizing/_intake.
• Root resolution: --cortex <dir> → $PYAUTO_CORTEX → <brain_parent>/PyAutoCortex
  → $PYAUTO_ROOT/PyAutoCortex; shell resolve_cortex() in agents/_common.sh (one
  line, mirrors resolve_mind); bin/_pyauto_root.sh _pyauto_is_root gains
  PyAutoCortex (drift fix vs the Python resolver). Project paths only from
  projects.yaml local_path/mirror (the documented exception; no literal in code).
• Gate grading is the Cortex script's: the daily job runs python3 scripts/cortex.py gates --grade --write with no Brain checkout; the Brain verb cortex gates --grade [--apply] is a thin wrapper translating --apply → write=True (prompt spelling
  kept; Cortex spelling unchanged).
• Dashboard normaliser strips the generated-comment line AND the Last updated
  banner line (md and html) so a no-op night commits nothing. Exit codes: --check
  1 = drift, 2 = bad args, other = renderer failure (the dashboard_refresh.yml
  contract). Only dashboard.html + batches/packets/*.html publish to Pages; the
  "markdown version" links point at the GitHub blob URL (as the Mind does).
• Board family: policy.yaml boards: gains cortex: PyAutoCortex (own line);
  _theme.ORGANS["cortex"] (tagline "Question. Run. Rule."; ink_light/ink_dark
  must pass WCAG 4.5:1 vs #ffffff/#0d1117; unique glow) + MARKS["cortex"]
  (line art on the 48×48 grid: ring, a folded-cortex wave path, a witness node;
  currentColor, no emoji); _board.py collect_cortex() sibling of
  collect_resume reads the Cortex dashboard.md counts table | [Label](#a) | N |
  (degrades silently when absent).
• Collect scoring (laptop tree only; never RAL; opt-in --pull runs the project's
  own <sync_cli> pull and stamps refreshed:): legs err (benign = every non-blank
  line is a *Warning* line or its indented continuation; Traceback/Error/
  Killed/OOM ⇒ FAIL; missing file ⇒ UNOBSERVABLE), wall (.out start/end stamps
  when it ends Finished.; else search.summary Time To Run read from the run dir
  or its .zip — the zip is authoritative, seven subhalo dirs are stale partial
  extractions; else UNOBSERVABLE) vs Budget:, version (result JSON top-level
  version under witness_file; else UNOBSERVABLE), checkpoint (only from a pull
  manifest <mirror>/.cortex/pull.json if present — phase 3 defines it; else
  UNOBSERVABLE, tagged RAL only), resume (Fit Already Completed /
  Resuming .* previous samples found in .out ⇒ FAIL), witness (a file matching
  witness_file newer than the run's submitted date ⇒ PASS). Logs found by
  **/output.<jobid>*.out / **/error.<jobid>*.err under mirror then local_path
  (depth ≤ 4). HEALTH = FAILED if any FAIL, SUSPECT if any UNOBSERVABLE, HEALTHY
  otherwise; delivered: counts HEALTHY. Emits the packet member block (TEMPLATE.md
  order) as markdown to stdout or --out; with --apply: move_phase(pulled) →
  awaiting-ruling, append - refreshed: (only when --pull ran or --refreshed
  given), update the record's member <state>.
• Admission (cortex plan): members = phases with State: ready, Witness:,
  Budget:, Lane: local-dev; session lane by shutil.which("gh") as _batch.py:57
  (cloud ⇒ report the ready count, plan nothing); greedy by Review-minutes against
  --budget (default 45), cheapest first; output == CortexPlan == in _batch.emit's
  shape; the launch payload carries no decision: the phase path, the project's
  sync_cli + submit verb, and the follow-up cortex.py move <phase> submitted --run <jobid> line. No autonomy cap consulted.
• Mind badge: _intake.py probes PYAUTO_CORTEX then Path(mind).parent / "PyAutoCortex" (no new imports); reads phases/**/*.md Gates: with a local
  30-line-header regex + a copy of GATE_REF_RE; maps canonical issue URL → phase rel;
  badges in-flight rows whose issue matches (head += " — ⚠️ gates a Cortex phase → <rel>"; HTML pills((…, "y"))). Draft prompts have no issue, so no badge there.
  Absent Cortex → nothing. Render-only.
• Tests depend on the real Cortex checkout (prompt task 7): tests.yml adds a third
  checkout (public repo, default token) and updates its "TWO repos" header prose;
  tests/test_cortex_conductor.py uses PyAutoCortex/tests/fixtures/skeleton and
  pytest.skips when the checkout is absent.

Files

PyAutoBrain (one PR, branch feature/cortex-conductor)

• bin/pyauto-brain: AGENT_SCRIPT[cortex], AGENT_DESC[cortex], CONDUCTOR_ORDER,
  header comment. Then bash bin/install.sh --write-agents-surface (regenerates the
  AGENTS.md commands block; test_skill_install.py checks it).
• agents/conductors/cortex/{AGENTS.md,cortex.sh,_cortex.py} — AGENTS.md opens with the
  Tier: conductor blockquote (Cortex = "the organism learns what is true"); the
  wrapper is profiling.sh's three lines; _cortex.py verbs census [--json],
  dashboard --check|--apply, gates [--grade] [--apply], plan [--budget N] [--lane ..], collect [--slot S] [--pull] [--refreshed ISO] [--apply] [--out F].
• agents/_common.sh resolve_cortex(); bin/_pyauto_root.sh _pyauto_is_root +
  PyAutoCortex.
• skills/cortex/SKILL.md + skills/cortex/cortex.md (≤200 lines each; links must
  resolve); skills/COMMANDS.md intro list + tier-1 table row.
• board/_theme.py ORGANS + MARKS cortex; config/policy.yaml boards row;
  board/_board.py collect_cortex() + the resume/board panels that read boards.
• agents/conductors/intake/_intake.py badge (census: c["cortex_gates"]; render md +
  html in In flight).
• docs/organs/cortex.md gains a "Driving it" section (verbs, the dashboard, the daily
  grade); docs/organs/cortex/workflows/ is NOT used — the workflow text lives in the
  Cortex PR (Brain merges first, so the Cortex workflows can reference Brain main).
• .github/workflows/tests.yml third checkout + prose.
• tests/test_cortex_conductor.py (renderer: every state renders, section order,
  counts table, normaliser ignores the date; plan: lane gating + budget; gates:
  injected fetch flips exactly one phase; collect: tmp mirror with one healthy and
  one resumed-run member, zip-authoritative wall, UNOBSERVABLE legs; badge: tmp Mind +
  tmp Cortex, in-flight row badged, absent Cortex silent); test_board_theme.py
  passes with the new entry; test_skill_install.py passes.

PyAutoCortex (one PR after Brain merges, branch feature/cortex-conductor)

• .github/workflows/dashboard_refresh.yml (mirror of the Mind's: two checkouts
  incl. PyAutoLabs/PyAutoBrain, check() with the exit-code contract, PR errors /
  push+cron+dispatch self-heal loop, both redispatch sites for
  pages_dashboard.yml; paths phases/** rulings/** batches/** projects.yaml epics.md dashboard.md dashboard.html; concurrency group cortex-main-writers shared with
  ledger_merge.yml), pages_dashboard.yml (mirror; enablement: true; index =
  dashboard.html, batches/packets/*.html → /packets/), gates_grade.yml (daily
  06:47 UTC + dispatch; contents: write, actions: write; runs python3 scripts/cortex.py gates --grade --write; 3-attempt fetch/reset/re-run/commit/push
  loop; commit cortex: gates graded — <n> flipped; redispatch cortex_check.yml +
  dashboard_refresh.yml; rc 1 from the script (unreadable ref) fails the job after
  committing whatever flipped). cortex_check.yml paths gain dashboard.md/.html and
  the "no self-heal" header sentence is updated.
• scripts/ledger_merge.py: EXCLUDED_NAMES += ("AGENTS.md", "TEMPLATE.md") with the
  comment reworded (instructional, not executable); LEDGER_FILES += ("dashboard.md", "dashboard.html") (generated; the self-heal commit must auto-merge). Tests extended
  (test_ledger_merge.py: the five doctrine paths are code; dashboards are ledger;
  workflow-enumeration tests updated for the three new workflow files).
• dashboard.md + dashboard.html — first render from the (empty) live tree, committed.
• AGENTS.md/REFERENCE.md: "Driving the Cortex" pointer to the Brain conductor and
  the four workflows; docs/schema_decisions.md 38+: every decision above (normaliser,
  observable legs, --pull doctrine, gates spelling, board row, carve-out, dashboards
  as ledger, tests depend on checkout).

PyAutoMind (one PR after Cortex merges, branch feature/cortex-conductor)

• .github/workflows/dashboard_refresh.yml: third checkout PyAutoLabs/PyAutoCortex
  at path: PyAutoCortex so the badge renders on Pages; comment why.

Repo settings (at ship, in-session)

gh workflow run repo_settings.yml --repo PyAutoLabs/PyAutoBrain -f mode=apply; confirm
delete_branch_on_merge=true on PyAutoCortex; delete the stale remote
feature/cortex-schema-skeleton by hand if the sweep did not. Pages: if the first
pages_dashboard.yml run fails on enablement, gh api -X POST repos/PyAutoLabs/PyAutoCortex/pages -f build_type=workflow once, then redispatch.

Execution (Opus subagents, sequential, one worktree cortex-conductor with

PyAutoBrain + PyAutoCortex + PyAutoMind)

• Issue via /create_issue; prompt → active/; active.md status: library-dev.
• Slice A (Brain core): registry + wrapper + _cortex.py census/dashboard/plan/gates
  • theme/policy/board + skills + COMMANDS + install surface + resolvers + tests.yml +
    renderer/plan/gates tests. Local commit.
• Slice B (Brain collect + badge): collect + _intake.py badge + their tests.
  Local commit. Full Brain suite green.
• Slice C (Cortex PR content): four workflows, ledger carve-out + tests, first
  dashboard render, docs + decisions. Local commit (rendered with the worktree Brain).
• Slice D (Mind PR): the checkout line. Local commit.
• Ship (Heart YELLOW ack as before): push Brain, PR, CI, merge; then Cortex PR (its
  dashboard_refresh.yml PR check renders against Brain main = merged); then Mind PR.
  Pages enable if needed; repo_settings dispatch; /prm close-out on the human's word.

Verification

• Witness: pyauto-brain cortex dashboard --check clean on the phase-1 skeleton
  fixture (--cortex PyAutoCortex/tests/fixtures/skeleton after --apply); the Pages
  site renders every state and the rulings (first deploy inspected by URL); the daily
  workflow flips a gated phase with closed refs to ready (dispatch it once against a
  fixture-like phase? — no live phases exist; verified by the unit test with injected
  fetch plus a dry gates --grade run on the empty tree); the Mind dashboard shows
  the badge (unit test with tmp trees; live Mind has no Cortex phases yet so no live
  badge — say so in the record).
• Brain: pytest tests -q green (both 3.12/3.13 legs in CI with the Cortex checkout);
  bash bin/install.sh --check-agents-surface clean; pyauto-brain board renders the
  Cortex family row; tenant firewall leg green.
• Cortex: cortex.py check OK; pytest tests -q green; ledger_merge.py classify of
  batches/AGENTS.md → code; dashboard --check clean on main after merge; Pages URL
  live.
• Mind: dashboard --check clean; lifecycle.py check OK.

Branch Survey

Suggested branch: feature/cortex-conductor (worktree root ~/Code/PyAutoLabs-wt/cortex-conductor/)

Cortex phase 2 — the Brain conductor, the dashboard, gate grading and the Mind badge

Type: feature
Target: pyautobrain
Repos:

• PyAutoBrain
• PyAutoCortex
• PyAutoMind
  Themes:
• dashboard
• mind-workflow
• hpc-gpu
  Difficulty: large
  Autonomy: supervised
  Priority: high
  Status: draft
  Consequence: judge
  Witness: pyauto-brain cortex dashboard --check is clean on the phase-1 skeleton; the Cortex Pages site renders every state and the rulings; the gate workflow flips a gated phase whose refs are closed to ready in one scheduled run; the Mind dashboard shows a "gates a Cortex phase" badge on a dev prompt named in a Cortex Gates:
  Review-minutes: 25
  Unattended: needs-slicing
  Epic: cortex-birth
  Phase: 2
  Parent: draft/feature/pyautocortex/cortex_birth_epic.md
  Filed: 2026-09-01

Phase 2 of 7 in the PyAutoCortex birth epic. Gate: phase 1. Gates phases 4
and 5. Renderer contract: the Brain PR merges BEFORE the Cortex and Mind PRs
— both dashboard workflows check out Brain main.

Natural slices if plan time says so: (a) conductor + render + workflows,
(b) gate grading, (c) admission + collect scoring, (d) the Mind badge.

Context

The Brain renders the Mind through the intake conductor
(agents/conductors/intake/_intake.py, census → dashboard --check/--apply),
regenerated by PyAutoMind/.github/workflows/dashboard_refresh.yml (checks out
PyAutoLabs/PyAutoBrain, self-heals main, then explicitly redispatches
pages_dashboard.yml because token pushes fire no events). The Cortex gets the
same shape with its own conductor. The nearest existing science-shaped code is
agents/conductors/profiling/_profiling.py: Mind-free, read-only, emits
decisions, never submits — the Cortex conductor is that, plus a renderer.

Known traps from the 2026-09-01 audit, all to be handled here rather than
worked around:

• agents/faculties/sizing/_sizing.py:92 hardcodes the Mind body map at
  import; agents/_pyauto_root.py:2-26 forbids absolute paths outside the
  workspace, and every science project lives at /mnt/c/Users/Jammy/Science/.
• _sizing.py:934-937 caps research/experiment at supervised, so
  batch plan rejects every science run — Cortex members need their own
  admission rule, not that one.
• registry_reconcile.yml:34 runs lifecycle.py issues without --drafts, so
  Mind gates are never auto-graded. The Cortex's grading must be the scheduled
  default, not opt-in.
• _intake.py:918-945: Blocked-by: never gates the Mind dashboard; the Mind
  badge here is render-only and must stay that way.

Task

1. agents/conductors/cortex/ registered in bin/pyauto-brain, with an
   AGENTS.md in the conductor register. Verbs: census, dashboard --check | --apply, gates --grade, plan, collect. Root resolution:
   PYAUTO_CORTEX → <brain_parent>/PyAutoCortex → $PYAUTO_ROOT/PyAutoCortex;
   do not extend resolve_mind. Project paths come from projects.yaml
local_path, resolved through a Cortex-scoped helper that is the one
   documented exception to the outside-workspace rule (the exception is scoped
   to rows of projects.yaml, nothing else).

2. Dashboard renderer (stdlib, like _intake.py:1657-1659 requires):
   sections Awaiting ruling (pulled, ordered failures → rulings-required →
   clean) → Running / submitted (live progress: job ids, budget vs elapsed
   from the batch record's refreshed: lines) → Ready → Gated (with the
   open refs and a 📋 chip) → Recent rulings → Epics (each card links its
   Mind half) → Projects (the where-to-look table straight from
   projects.yaml). Titles/keys parametrised — no Mind literals (_intake.py's
   :58, :744-746, :1631, :1988, :1997, :2294 are the pattern to avoid).
   Markdown + HTML, both with a "markdown version" link per section.

3. Cortex workflows (Cortex repo, Brain PR ships their text under
   docs/organs/cortex/workflows/ for the Cortex PR to copy): dashboard_refresh.yml
   mirroring the Mind's including the self-heal and the explicit
   pages_dashboard.yml redispatch; pages_dashboard.yml publishing
   dashboard.html as index and batches/packets/*.html; ledger_merge.yml;
   gates_grade.yml daily running cortex gates --grade --apply (flips
   gated → ready and commits) — this is the one scheduled job that mutates
   state, and it may only ever move gated → ready.

4. Admission rule (cortex plan): a phase is plannable when State: ready,
   witness present, budget present, and lane is the session's (always
   local-dev — a cloud session reports the ready count and plans nothing,
   per the laptop-lane ruling). No autonomy cap is consulted; science members
   are supervised by definition and the ruling is the human's. Output: the
   proposed members with review-minutes against the slot budget, same shape as
   batch plan.

5. Collect scoring (cortex collect): for each submitted/running
   member, read the batch record's refreshed: lines and the pulled tree
   under mirror/local_path: .err size against the benign baseline, wall
   vs Budget:, version stamp in the result JSON, checkpoint.hdf5 present
   and non-empty, no resume marker in .out (Fit Already Completed /
   Resuming .* previous samples found), the witness file present and scored
   against Witness:. Emits the packet member block
   (PyAutoMind/batches/packets/TEMPLATE.md member shape) and moves the phase
   pulled → awaiting-ruling. It never reads sacct state as health and
   never touches RAL — the pull is the human's hpc/sync pull, recorded as a
   refreshed: line.

6. Mind badge (_intake.py): when a Cortex checkout is beside the Mind (or
   PYAUTO_CORTEX resolves), read every Cortex phase's Gates:; any Mind
   prompt whose issue/PR matches gets a render-only "gates a Cortex phase →
   " badge. Absent Cortex → no badge, no error. Add the Cortex checkout
   to PyAutoMind/.github/workflows/dashboard_refresh.yml (Mind PR).

7. Tests: tests/test_cortex_conductor.py against the phase-1 skeleton
   fixture (every state renders; grading flips exactly one phase on a mocked
   closed ref; collect scores a fixture tree with one healthy and one
   resumed-run member; a cloud-lane session plans nothing and reports the
   count). tests.yml checks out PyAutoCortex beside PyAutoMind.

8. Ledger carve-out (phase-1 follow-up, ruled in 2026-09-01). In the
   Cortex's scripts/ledger_merge.py, prose that merely lives under a ledger
   dir is code: rulings/AGENTS.md, batches/AGENTS.md,
   batches/packets/AGENTS.md, batches/packets/TEMPLATE.md,
   batches/reviews/AGENTS.md (pattern: any AGENTS.md or TEMPLATE.md
   under LEDGER_DIRS) must classify as code so a claude/** branch cannot
   auto-merge doctrine edits. Test it; record it in docs/schema_decisions.md.
   The Mind has the same trait and keeps it — its call, not this phase's.

9. Repo settings (phase-1 follow-up, ruled in 2026-09-01). PyAutoCortex was
   born after the last PyAutoBrain/.github/workflows/repo_settings.yml sweep
   (org enumeration covers it; delete_branch_on_merge=false today, and the
   merged feature/cortex-schema-skeleton survived on the remote). Dispatch
   the sweep once (gh workflow run repo_settings.yml), confirm the setting
   flips and the stale remote branch is collected (or delete it by hand and
   say so), and add PyAutoCortex to whatever per-repo config the sweep reads
   if it is not purely org-enumerated.

Acceptance

• The witness above; Brain tests green; pyauto-brain board shows the Cortex
  board family row from phase 0 populated (counts only — the strip is phase 6).
• PR order: PyAutoBrain → PyAutoCortex (workflows) → PyAutoMind (badge
  workflow checkout).

Out of scope

• The batch conductor's second member kind and separate review-at: (phase 5)
  — cortex plan/collect here are standalone verbs the human runs in a
  laptop slot; phase 5 folds them into batch.
• Migrating any real phase or ruling (phase 4).
• Any dispatch. The conductor never submits.