Bootstrap (the repo has no main)

1. Clone PyAutoLabs/PyAutoCortex into the canonical root
   (/home/jammy/Code/PyAutoLabs/PyAutoCortex). Bootstrap commit on main: LICENSE
   (MIT, copy the Mind's, Copyright (c) 2026 Jammy2211), README.md stub, .gitignore
   (copy the Mind's). Push main — the birth commit of an empty repo, not a rewrite.
2. worktree_create cortex-schema-skeleton PyAutoCortex PyAutoBrain → branch
   feature/cortex-schema-skeleton; worktree-root AGENTS.md symlink → copy first
   (phase-0 trap).
3. After AGENTS.md exists in the Cortex worktree (with the generated-block markers,
   below): python3 PyAutoMind/scripts/repos_sync.py --write --root <worktree> from the
   worktree — generates CLAUDE.md (fixed pointer text @AGENTS.md + comment),
   .claude/hooks/session-start.sh (byte-identical copy of the Mind's policy hook) +
   .claude/settings.json, and splices the organism-map / never-rewrite-history /
   remote-sessions blocks into AGENTS.md. Commit the generated files in the PR.
   No Mind PR: session_hook_propagate.yml reads every repos.yaml row and the
   Cortex row already exists (the prompt's "add to the fan-out list" is satisfied).

Layout

PyAutoCortex/
  AGENTS.md  CLAUDE.md(gen)  README.md  REFERENCE.md  LICENSE  .gitignore
  projects.yaml                      # science body map — CODE, not ledger (see decisions)
  epics.md                           # Mind schema + `- mind-half:`; empty at birth
  phases/<project>/<slug>.md
  rulings/AGENTS.md  rulings/<YYYY>/<MM>/R-<YYYYMMDD>-<nn>.md
  batches/AGENTS.md  batches/packets/{AGENTS.md,TEMPLATE.md}  batches/reviews/AGENTS.md
  docs/schema_decisions.md
  policy/never_rewrite_history.md  policy/remote_sessions.md   (copies; spliced into AGENTS.md by repos_sync)
  scripts/cortex.py  scripts/ledger_merge.py
  tests/test_cortex.py  tests/test_ledger_merge.py  tests/fixtures/skeleton/  tests/fixtures/empty/
  .github/workflows/cortex_check.yml  .github/workflows/ledger_merge.yml
  .claude/hooks/session-start.sh(gen)  .claude/settings.json(gen)

No skills/ (nothing to expose) → no install.sh change (its ORGAN_REPOS is a
hardcoded list only Brain's AGENTS.md actually uses); recorded in decisions.

Header convention (all .md registries)

Line 1 # <title>; Key: value lines within the first 30 lines, first occurrence
wins, block ends at the first blank line; list-valued keys as a bare Key: line
followed by - item lines (the Mind's light header — regexes mirrored from
lifecycle.py:292-323 / _intake.py:576-596,812-836). No YAML frontmatter.

projects.yaml — restricted YAML subset, stdlib-parsed

Keep the name (epic names it; Mind reads real YAML with PyYAML). Documented subset:

<key>:                        # column 0, ^[a-z][a-z0-9_]*$
  <field>: <scalar>           # exactly two spaces; fixed field set, unknown field = error
  sync_verbs: [pull, push]    # flow list of bare words — the only list

Scalars bare unless they contain #, : or edge spaces, then "..." with no escapes;
comments on their own line or after #; no block lists, nesting, anchors, ---.
Fields: remote (owner/repo | none), local_path (absolute laptop path — the
Cortex-only exception to the workspace-paths rule, stated in the file header and
AGENTS.md), ral_root, mirror (path | none), sync_cli, sync_verbs, ledger,
witness_file (glob), partition (gpu | ral | both), status (active | dormant).
Ships with the schema comment block + one worked example as a commented-out row
(real rows are phase 3). ~40-line line-loop parser in cortex.py; a test guarded by
pytest.importorskip("yaml") asserts yaml.safe_load(text) == parse(text) on the
fixture so the subset never drifts out of real YAML. Code, not ledger: like
repos.yaml (Mind ledger_merge.py:57-63), and worse — sync_cli/local_path are
paths phase 2's conductor will execute under. Deviation from the prompt, recorded.

Phase file phases/<project>/<slug>.md

Headers: Project: (must equal the directory name AND be a projects.yaml key),
Phase: (integer, unique per project), State: (planned | gated | ready | submitted | running | pulled | awaiting-ruling | accepted | rerun | dropped), Gates: (comma-
separated refs, Repo#N shorthand with default owner PyAutoLabs or issue/PR URL —
GATE_REF_RE copied verbatim from lifecycle.py:879-882; no owner/Repo#N form,
the lookbehind rejects it), Gates-cleared: (date; written by gates --grade --write),
Gate-override: (reason; written by move --override), Witness: (mandatory before
submitted), Budget: (H+:MM), Runs: (comma-separated job stems; the index of
the body's run lines), Ruling: (chain-head ruling id), Lane: local-dev (always),
Review-minutes:, Epic: (shared slug — join key with Mind), Filed:.
Body: ## Question, ## Witness, ## Where to look, ## Runs, ## Ruling.

Run lines (## Runs) — SLURM notation, strict grammar

- <stem>[_<task>|_[<a>-<b>,<c>]]: <run-state> — <partition> — submitted <YYYY-MM-DD> — wall <H+:MM>[ — <note>]
    pulled_to: <path>   |  after: <run>  |  resumes: <run>  |  where: <path>  |  ruled: <id>

run-state ∈ submitted | running | done | failed | timeout | void | legacy | legacy_wrong
(void = cancelled / never produced a step; legacy* = quarantine — a run state,
never a phase state). -- accepted for — (phone keyboards); check normalises.
Structured facts on indented continuation lines, never in the note. check enforces:
every line matches; task sets on one stem are disjoint within a phase (job ids are
unique per phase, not globally — one array may feed two phases); Runs: header ==
set of body stems; pulled ⇒ ≥1 done|legacy run with pulled_to:; legacy* ⇒
where:; after:/resumes: targets are runs of the same phase.

Transition table (cortex.py move; rule owns every ruling edge)

Rulings rulings/<YYYY>/<MM>/R-<YYYYMMDD>-<nn>.md

Id R-YYYYMMDD-nn (2-digit per-day sequence, global; rule assigns; filename == id).
Headers: Project:, Phase: (single phase path), Runs: (⊆ the phase's runs),
Ruling: (accept | rerun | drop | leave-to-finish), Supersedes: (optional single
id), Batch: (optional <date>-<slot> — the join for rulings filed together),
Reviewed-at:, Review-minutes-actual:, Follow-ups: (GitHub refs validated by
GATE_REF_RE; the issue is created before rule runs). Body: ## Ruling (the
human's words verbatim), ## Evidence. One ruling file per phase; a multi-phase
ruling (a REWIND) is N files with the same body and one Batch: (rule --also <phase>
fans out). rulings/AGENTS.md: append-only, supersede-never-edit, and a verdict
recorded only outside the Cortex does not exist.
check enforces: id unique and == filename; Supersedes: resolves, ≠ self, lexically
smaller, same project+phase; at most one successor per ruling (a chain, not a
tree — "supersede the head"); the phase's Ruling: is a chain head naming that phase;
head verb ↔ state (accept ⇒ accepted, drop ⇒ dropped, rerun ⇒ rerun|ready| submitted+, leave-to-finish ⇒ non-terminal); ruling Runs: ⊆ phase runs.

Batches (rolling board)

Copy the Mind's batches/AGENTS.md, packets/AGENTS.md, packets/TEMPLATE.md,
reviews/AGENTS.md; change: review-at: per Cortex batch; the packet is a rolling
board (members join when a phase reaches pulled; submitted/running hold no review
control; each pull appends refreshed:); delivered: = .err clean + wall < budget +
version stamp + checkpoint.hdf5 sane (never sacct COMPLETED); member line
<slug>: <phase path> — <runs> — <review-minutes> — <state>; one review grammar
(the Mind's two files disagree — take TEMPLATE.md's parse-stable form):
## <slug> — <HEALTH> / - decision: accept|rerun|drop|leave-to-finish / - ruled: yes|no
/ note paragraph; the new/main?filename= commit link points at the Cortex. Member
block lifted from TEMPLATE.md: Question · Witness · Health evidence · Readout · Ruling ·
Where to look · Est. review-minutes.

scripts/cortex.py (stdlib only; main(argv), no import-time side effects; --root)

• check — the rules above (phases, runs, rulings, gates invariant, batch member
  lines); hermetic; lifecycle.py-style report (cortex check: OK / DRIFT + - …
  lines, exit 1). Legs take root: Path (testable with tmp_path).
• gates [--grade [--write]] — offline: list gated phases + refs. --grade: per ref
  gh api repos/<o>/<r>/issues/<n> --jq '{state, state_reason, merged_at: .pull_request.merged_at, is_pr: (.pull_request != null)}'
  (stdlib urllib fallback as lifecycle.py:672-703, User-Agent pyautocortex).
  Cleared = PR ⇒ merged_at != null (closed-unmerged = dead gate, reported); issue ⇒
  state == closed and state_reason ∈ {completed, null} (not_planned/duplicate =
  dead gate); any unreadable ⇒ fail closed. --grade reports only; --write flips
  gated→ready (+Gates-cleared:) and ready→gated on reopen (rules above). Phase 2
  schedules --write.
• rule <phase> <verb> --body <file> [--supersedes <id>] [--batch <slot>] [--minutes n] [--follow-up <ref>]... [--also <phase>]... — assigns the next id, writes the file(s),
  updates Ruling: + State: per the table, refuses to touch an existing ruling.
• move <phase> <state> [--run <id>] [--reason ..] [--override ..] [--partial] — the
  table; refuses ruling edges.
• new <project> <slug> --phase <n> [--gates ..] [--epic ..] [--legacy-run <id>]... —
  writes a phase file from a template.

scripts/ledger_merge.py

Copy of the Mind's (182 lines, stdlib) with LEDGER_DIRS = ("phases/", "rulings/", "batches/"), LEDGER_FILES = ("epics.md",), docstring/comments re-pointed. Plus
append-only enforcement the Mind lacks: classify via git diff --name-status; M/D/R
on rulings/** is code (needs a human). Mirror tests/test_ledger_merge.py incl. the
self-consistency assertion that the workflow and the script are not ledger.

Workflows

• cortex_check.yml — modelled on lifecycle_drift.yml (plain checkout, no Python
  setup): on push to main / PR / dispatch with paths: phases/** rulings/** batches/** projects.yaml epics.md scripts/** tests/**: python3 scripts/cortex.py check, then
  pip install pytest pyyaml && python3 -m pytest tests -q. No self-heal.
• ledger_merge.yml — from mind_ledger_merge.yml: repo literal, name, concurrency
  group, paths; drop the Brain checkout + freshness leg; blocking check =
  cortex.py check run on the trial-merge tree (after git merge --no-ff, before
  git push) — that is what catches the ruling-id race (two branches both assign
  R-…-03); commit prefix cortex:; heal list → cortex_check.yml.

Docs

AGENTS.md: what the Cortex is, the boundary line, the ruling-of-record rule, the
workspace-paths exception, the laptop-lane closures quoted verbatim from
batch_science_lane.md:34-50 "What is now out of scope, and why", cortex.py verbs,
and the generated-block markers (<!-- repos_sync:map:begin/end -->, the history and
remote-sessions markers as in Gut's/Nerves' AGENTS.md — subagent reads
repos_sync.py:600-661 for the exact names). README.md (Mind register).
REFERENCE.md (Mind H2 shape): what a phase looks like · how a phase flows (the table)
· repository layout · run-line grammar · ruling schema · batch record + review grammar ·
the restricted YAML subset · how the ledger lands (ledger_merge.yml) · bootstrap.
docs/schema_decisions.md (dated): every choice above the epic did not fix — id format,
per-phase rulings + Batch:, chain-not-tree, accepted-not-terminal via supersede,
self-loop waves, --partial, legacy-born phases, void, gate "cleared" definition,
--grade report-vs-write, reopen demotion, projects.yaml as code + YAML subset,
no owner/Repo#N, run-line grammar + continuation lines, per-phase job-id uniqueness,
no skills/install in phase 1, no Mind PR, fixture witness, trial-merge check.

Fixtures and tests (the witness)

tests/fixtures/skeleton/: projects.yaml (project example); phases/example/ with
ten files, one per state, covering: gated (URL ref + Repo#N ref); ready with
Gates-cleared: and another with Gate-override:; submitted with a failed wall 0:00 line then a second run; running with 342091_[0-8,10]: done + 342091_9: failed + an after: chain; pulled with pulled_to:; a leave-to-finish ruling on
the running phase; accepted with chain 01→02 (R-20260901-01/-02, same
project+phase); legacy and legacy_wrong runs with where:; one batch record + one
review file. tests/fixtures/empty/ (empty map, no phases) passes check.
tests/test_cortex.py: sys.path.insert + import cortex for pure functions with an
injectable fetch; one subprocess test per verb for exit codes; move/rule/new
on a copytree of the fixture; negatives as tmp_path mutations, one per check rule
(duplicate phase number, unknown project, dir≠Project, dangling/duplicate/self
Supersedes:, superseded-as-Ruling:, header/body run mismatch, overlapping task
sets, owner/Repo#N, missing Gates-cleared:, verb↔state mismatch); yaml parity.
Witness: python3 scripts/cortex.py check --root tests/fixtures/skeleton exits 0 and
python3 scripts/ledger_merge.py classify <every fixture path> classifies each.

Brain (small PR, config only — promised by phase 0's record)

config/policy.yaml test_witness: gains pyautocortex: PyAutoCortex/tests (key =
normalise_repo form; the row has no package:, as required); tests/test_policy_seams.py
drops the PyAutoCortex WITNESS_EXEMPT entry. No conductor code (phase 2).

Execution

• Issue on PyAutoMind via /create_issue; prompt → active/; active.md
status: library-dev, worktree ~/Code/PyAutoLabs-wt/cortex-schema-skeleton
  (worktree_check_conflict cortex-schema-skeleton PyAutoCortex PyAutoBrain — Brain
  claim from phase 0 is released).
• Bootstrap by the slice-A subagent (clone, birth commit, worktree).
• Slice A (Fable subagent): bootstrap + docs + projects.yaml + epics.md + policy
  copies + batches docs + fixtures + schema_decisions.md + workflow files; then
  repos_sync --write --root <worktree>; local commit. I review the schema files.
• Slice B (Fable subagent): cortex.py, ledger_merge.py, tests; run the witness,
  pytest, repos_sync --check; Brain policy row; local commits.
• Heart gate at ship (YELLOW earlier today: PyAutoArray PR 9d old; no release rehearsal —
  re-read vitals; ack needed again unless GREEN), then push + PRs: PyAutoCortex#1
  (skeleton), PyAutoBrain (witness row). /prm on the human's word. Merge Cortex first
  (Brain's row is inert either way).

Verification

• Witness (fixture check exit 0; every fixture path classified).
• pytest tests -q green in the Cortex worktree; cortex_check.yml green on the PR;
  ledger_merge.yml never fires on this PR (branch is feature/*, trigger is claude/**).
• repos_sync.py --check --root <worktree> 15 legs OK with the Cortex checkout present
  (hooks written, CLAUDE.md pointer, map/history/remote blocks spliced).
• Brain: pytest tests/test_policy_seams.py -q green with the exemption removed.
• The live tree outside tests/fixtures/ holds no phases and no rulings.

Branch Survey

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

Cortex phase 1 — the schema and the repo skeleton

Type: feature
Target: pyautocortex
Repos:

• PyAutoCortex
• PyAutoMind
  Themes:
• mind-workflow
• hpc-gpu
  Difficulty: large
  Autonomy: supervised
  Priority: high
  Status: draft
  Consequence: judge
  Witness: python3 scripts/cortex.py check exits 0 on a skeleton holding one example project, one phase in every state, and two rulings (one superseding the other); ledger_merge.py --check classifies every file
  Review-minutes: 25
  Unattended: needs-slicing
  Epic: cortex-birth
  Phase: 1
  Parent: draft/feature/pyautocortex/cortex_birth_epic.md
  Filed: 2026-09-01

Phase 1 of 7 in the PyAutoCortex birth epic. Gate: phase 0 (the repo must
exist). Gates phases 2 and 3.

This is the phase that decides what the Cortex is. Everything the human ruled
on 2026-09-01 (epic ledger, "The decision") is fixed input here; the work is
turning it into files, schemas and one lifecycle script. It is a design-heavy
prompt and may need slicing at plan time — the natural seam is (a) schemas +
docs, (b) cortex.py + ledger-merge.

Context

The Cortex is a run-and-ruling registry, not a prompt lifecycle. The unit is a
phase of a project, which spawns runs (SLURM job ids) and ends in a
ruling. Three science projects exist today with three ledger formats
(autolens_profiling PROGRAMME/DECISIONS/RESULTS; subhalo_validation
state.md + journal + results_summary; euclid — none yet) and three hpc/sync
CLIs. The schema must be able to describe all three without changing them.

The Mind's conventions to keep where they fit: a light, human-writable header
(no YAML frontmatter); ledger dirs that auto-merge (ledger_merge.py
default-deny classifier); never_rewrite_history.md; the session-start hook
propagated from Mind's policy/session_start_hook.sh; markdown a human edits by
hand as the source of truth for registries.

Task

1. projects.yaml — the science body map. One row per project: name,
   remote (may be none), local_path (laptop, outside the workspace — this
   is a Cortex-only exception to the workspace-paths rule and must say so),
   ral_root, mirror (laptop pull root, may be none), sync_cli (path +
   which verbs it has), ledger (the project's own commentary ledger),
   witness_file (glob), partition, status: active | dormant. Seed rows
   are phase 3's job; here the schema plus one worked example.
2. Phase files. phases/<project>/<slug>.md with a header mirroring the
   Mind's shape: Project:, Phase: (distinct integers within a project),
   State: (planned | gated | ready | submitted | running | pulled | awaiting-ruling | accepted | rerun | dropped), Gates: (GitHub issue/PR
   refs only — Repo#N shorthand or URL, comma-separated; the same GATE_REF_RE
   grammar as PyAutoMind/scripts/lifecycle.py:879-898, and it clears only when
   every ref closes), Witness: (pre-registered, mandatory before submitted),
   Budget: (wall), Runs: (job ids, appended as they are submitted),
   Lane: local-dev (always; the field exists for the batch conductor's
   filter), Review-minutes:, Epic: (the shared slug — join key with Mind),
   Filed:. Body: Question / Witness / Where to look / Runs / Ruling ref.
   Quarantine: legacy and legacy_wrong are states of a run, recorded in
   the phase's Runs block, never of a phase.
3. rulings/ — the ledger of record. rulings/<YYYY>/<MM>/<id>.md, id =
   R-<YYYYMMDD>-<nn>. Header: Project:, Phase:, Runs:, Ruling:
   (accept | rerun | drop | leave-to-finish), Supersedes: (optional ruling
   id), Reviewed-at:, Review-minutes-actual:, Follow-ups: (GitHub refs —
   the issue is created at filing, see epic). Body: the human's words verbatim,
   then evidence pointers. Append-only; a wrong ruling is superseded by a new
   one, never edited. State the rule in rulings/AGENTS.md: a verdict
   recorded only outside the Cortex does not exist.
4. batches/. AGENTS.md, packets/, reviews/ — copy the Mind's
   record schema and change what differs: review-at: is per Cortex batch;
   the packet is a rolling board (members are added when pulled, nothing
   in submitted/running holds review control, refreshed: lines are the
   record of each pull); delivered: = .err clean + wall < budget + version
   stamp + checkpoint.hdf5 sane; member line <slug>: <phase path> — <runs> — <review-minutes> — <state>. One review vocabulary: accept | rerun | drop | leave-to-finish — retire the Mind's reviews/AGENTS.md:24 science
   line and packets/TEMPLATE.md:64's longer list in favour of this (phase 4
   edits the Mind copies; here, the Cortex is authoritative). Lift the member
   block (Question · Witness · Health evidence · Readout · Ruling · Where to
   look · Est. review-minutes) from PyAutoMind/batches/packets/TEMPLATE.md.
5. scripts/cortex.py — one script, stdlib only: check (every phase file
   parses, states legal, every submitted+ phase has a witness, every ruling id
   unique and every Supersedes: resolves, every project in a phase path is in
   projects.yaml), gates (offline: list open gates; --grade polls GitHub
   via gh and reports which gated phases are now ready — advisory here,
   the daily flip is phase 2's workflow), rule (append a ruling from a body
   file, assign the id, update the phase's State: and ruling ref), move
   (state transitions with the legal-transition table enforced).
6. scripts/ledger_merge.py adapted from the Mind's: ledger dirs
   phases/ rulings/ batches/, ledger files projects.yaml, epics.md.
   policy/never_rewrite_history.md copied; policy/session_start_hook.sh
   pulled in by the Mind's session_hook_propagate.yml (add the Cortex to its
   fan-out list — a Mind PR).
7. epics.md — same schema as the Mind's, plus - mind-half: linking the
   Mind entry by slug; the Mind's entries gain the reciprocal - cortex-half:
   in phase 4.
8. AGENTS.md, CLAUDE.md, README.md, REFERENCE.md — the organ's
   own docs in the Mind's register. AGENTS.md carries the laptop-lane closures
   verbatim from PyAutoMind/draft/research/euclid/batch_science_lane.md
   ("What is now out of scope, and why") so nobody re-derives them.

Acceptance

• The witness above.
• A dated docs/schema_decisions.md recording every choice made here that the
  epic ledger did not already fix (id format, transition table, what a run vs
  a phase is), so phase 2's conductor reads decisions rather than guessing.
• PRs: PyAutoCortex (skeleton), PyAutoMind (hook fan-out only).

Out of scope

• Seeding real projects (phase 3) and migrating real phases/rulings (phase 4).
• Any Brain code (phase 2). The gates --grade verb here is a hand tool; the
  scheduled grading lives in phase 2.
• A GitHub Pages site — phase 2 builds the renderer; do not hand-write HTML.