Separate pinned canon from stack research

Move imported canonical repository trees to libs/, establish BASE-bound research workspaces, update EPAC's UCNS path, and align stack provenance/usage documentation.

Author: erinepshovel-code

README.md

@@ -2,66 +2,106 @@
 
 "This is how it comes together."
 
-`The-Interdependency/stack` is the consolidated, provenance-bearing aggregation of the
-organization's core repositories. It is an integration surface, not a source of truth:
-each `research/` snapshot is pinned to an exact source commit, and canonical edits still
-happen in the individual repositories.
+`The-Interdependency/stack` is the organization's composition forge. Pinned views of
+canonical repositories are brought together here so stack-local research can test
+relations among them and, when warranted, form new projects such as EPAC and AHBG.
+
+Canonical authority does **not** transfer into stack when a repository is imported.
+For repositories with an independent authority:
+
+- `libs/<repo>/` is the read-only, manifest-pinned canonical repository view.
+- `research/<repo>/` is stack-local current research against that pinned base.
+- accepted changes to an existing project route back to its owning repository;
+- a genuinely new composed project remains stack-local until it earns an independent
+  repository and release lifecycle.
 
 ## Layout
 
 ```text
 stack/
-├── skill-lib/               # full snapshot of The-Interdependency/skill-lib
-├── research/
-│   ├── metapat/              # full snapshot — semantic authority (Meta Energy Theory)
-│   ├── ucns/                 # full snapshot — geometry and mathematical representation
-│   ├── edcm/                 # full snapshot — measurement and text-gonol construction
-│   ├── epac/                 # placeholder — energy particle affixiation coupling (no source yet)
-│   ├── pcea/                 # full snapshot — prime circle encryption algorithm
-│   └── ptcna/                # full snapshot — prime tensor circled neural architecture
-├── libs/                     # empty scaffolds reserved for consolidated library surfaces
-│   ├── skill-lib/
+├── skill-lib/               # operational pinned snapshot of org build/evidence doctrine
+├── libs/                    # manifest-pinned canonical repository views; do not edit
 │   ├── metapat/
 │   ├── ucns/
 │   ├── edcm/
-│   ├── epac/
 │   ├── pcea/
-│   └── ptcna/
-├── backend/                  # empty scaffold
+│   ├── ptcna/
+│   ├── epac/                # canon slot unpopulated until EPAC graduates
+│   └── skill-lib/           # reserved; root skill-lib/ remains the operational special case
+├── research/                # stack-local work; never source authority by location
+│   ├── metapat/             # current METAPAT research + BASE.json
+│   ├── ucns/                # current UCNS research + BASE.json
+│   ├── edcm/                # current EDCM research + BASE.json
+│   ├── pcea/                # current PCEA research + BASE.json
+│   ├── ptcna/               # current PTCNA research + BASE.json
+│   └── epac/                # emerging composed project; no independent repo yet
+├── ahbg/                    # emerging composed benchmark/game workspace
+├── backend/                 # stack-level application scaffold
 ├── frontend/
-│   └── cli/                  # empty scaffold
-├── STACK_MANIFEST.md         # human-readable provenance record
-└── stack-manifest.json       # machine-readable stack manifest (schema 1.0.0)
+│   └── cli/                 # stack-level application scaffold
+├── STACK_MANIFEST.md        # human-readable provenance and boundary record
+└── stack-manifest.json      # machine-readable work graph
 ```
 
+`src/` inside an imported repository keeps its normal Python meaning: it is that
+repository's package-source layout. It does not mean "canonical source" for stack.
+
 ## Usage guidance
 
-- **Start at [`STACK_MANIFEST.md`](STACK_MANIFEST.md).** It pins the exact source commit,
-  branch, authority, snapshot path, and license status of every participant.
-- **Read research sources in place.** `research/<repo>/` contains that repository's full
-  tracked tree at the pinned commit (README, AGENTS/CLAUDE, source, tests, and docs).
-- **Do not edit `research/` snapshots as doctrine.** Edit the canonical repository first,
-  then refresh this aggregation with the procedure in `STACK_MANIFEST.md`.
-- **`libs/` is reserved, not implemented.** Its scaffolds mark where consolidated library
-  surfaces will live; nothing in this repo depends on them yet.
-- **`backend/` and `frontend/cli/` are empty scaffolds** reserved for stack-level
-  application work.
+### Read canon
+
+Start at [`STACK_MANIFEST.md`](STACK_MANIFEST.md), then read the pinned repository in
+`libs/<repo>/`. Those trees are exact imported views of the source commits recorded by
+the manifest. Do not make canonical edits there.
 
-## Replaying a snapshot
+### Do current research
 
-From a clean checkout of the source repository at the desired commit:
+Work in `research/<repo>/`. Each established project workspace has a `BASE.json` that
+binds the research to an exact owning repository, commit, and `libs/` path.
 
 ```bash
-git -C <checkout> archive <commit> | tar -x -C research/<name>/
+cat research/ucns/BASE.json
 ```
 
-Then update `STACK_MANIFEST.md` and `stack-manifest.json`, recompute the work-graph digest,
-and commit with the new source commit SHAs in the message.
+If the result changes UCNS itself, prepare the change for `The-Interdependency/ucns`.
+After upstream merge, refresh `libs/ucns/` and update `research/ucns/BASE.json`.
+
+### Compose something new
+
+New cross-project work may be born in stack. It does not inherit the authority of its
+inputs. While it is still stack research, keep its standing explicit. When it becomes
+coherent enough to graduate, create its independent repository, preserve provenance,
+package/release it, then let stack consume the released project rather than a hidden
+stack-local implementation.
+
+EPAC is currently in this pre-graduation state.
+
+## Refreshing a canonical view
+
+From a clean checkout of the owning repository at the desired commit:
+
+```bash
+rm -rf libs/<name>/*
+git -C <checkout> archive <commit> | tar -x -C libs/<name>/
+```
+
+Then update `STACK_MANIFEST.md`, `stack-manifest.json`, and the matching
+`research/<name>/BASE.json`; recompute the work-graph digest; and commit with the exact
+source commit in the message.
+
+## Boundaries
+
+- `libs/` is a pinned view, not a transfer of authority.
+- `research/` is mutable stack-local work, not doctrine by location.
+- moving work from `research/` to `libs/` is not a promotion mechanism; `libs/` is
+  populated only from an owning canonical repository at an exact commit.
+- proof, measurement, and semantic standing do not transfer merely because projects are
+  composed in stack.
 
 ## hmmm
 
-- Whether `libs/` should eventually contain package-only sources, built artifacts, or full
-  vendored copies remains an open stack-integration decision.
-- The exact shape of `backend/` and `frontend/cli/` is not yet declared.
-- `research/epac/` is a placeholder until an energy particle affixiation coupling source
-  repository exists.
+- `skill-lib/` remains a special operational root snapshot instead of using the same
+  `libs/` + `research/` pair.
+- The exact graduation automation from stack-local project to independent repo + package
+  is not yet implemented.
+- The exact long-term shape of `backend/` and `frontend/cli/` remains undeclared.

STACK_MANIFEST.md

@@ -1,30 +1,58 @@
 # STACK_MANIFEST.md
 
-Provenance record for the consolidated snapshots in `The-Interdependency/stack`.
+Provenance and authority-boundary record for `The-Interdependency/stack`.
 
-- Snapshot UTC: `2026-08-22T10:19:43Z`
+- Source snapshot UTC: `2026-08-22T10:19:43Z` (source commits unchanged by this layout migration)
+- Layout migration UTC: `2026-08-30T02:52Z`
 - Stack-manifest schema: `the-interdependency.stack-manifest` version `1.0.0`
 - Work-graph digest (SHA-256 over canonical `repositories` + `boundaries` JSON):
-  `f7a56ead99174598fd37e044f25c88b5dd47f53f9e4836c41620781bc3e6494a`
+  `0760abd60f089266405aa589063a7533f485761e2bd25faa44f2eac64fb89f7d`
 - Machine-readable copy: [`stack-manifest.json`](stack-manifest.json)
 
+## Directory contract
+
+For an established repository participating in stack:
+
+```text
+libs/<repo>/       = exact imported canonical repository view at the manifest commit
+research/<repo>/   = mutable stack-local research based on that imported view
+```
+
+`libs/` does not gain authority by containing a copy. The owning repository remains
+canonical. `research/` does not gain canon status by producing a useful result.
+
+A Python `src/` directory inside `libs/<repo>/` retains the normal package-layout
+meaning used by that repository.
+
 ## Participants
 
-| Repository | Exact source commit | Source branch | Authority | Snapshot path |
+| Repository | Exact source commit | Source branch | Authority | Stack relation |
 |---|---|---|---|---|
-| `The-Interdependency/skill-lib` | `fb3b53a7629f7f03ecf255167d52c13abef1a979` | main | organization-wide build and evidence doctrine | `skill-lib/` |
-| `The-Interdependency/metapat` | `34d954aa1e2092e615b03a180500f6b6977f501e` | main | semantic authority (Meta Energy Theory) | `research/metapat/` |
-| `The-Interdependency/ucns` | `1975fe70cf4e0826a8020c2da3047569e277af64` | main | geometry and mathematical representation | `research/ucns/` |
-| `The-Interdependency/edcm` | `7951ca32ba0f2494dc68ff9b7f6a80151918a56d` | main | measurement and text-gonol construction | `research/edcm/` |
-| `The-Interdependency/pcea` | `4d2c581448b97bfb71da92b35487e74e6e3bcedc` | main | prime circle encryption algorithm | `research/pcea/` |
-| `The-Interdependency/ptcna` | `97abdd1bbda61a68e0aac8595a32a3cb0ce73487` | main | prime tensor circled neural architecture | `research/ptcna/` |
-| `The-Interdependency/epac` | `hmmm` | — | placeholder scaffold for energy particle affixiation coupling; no source repository exists yet | `research/epac/` |
+| `The-Interdependency/skill-lib` | `fb3b53a7629f7f03ecf255167d52c13abef1a979` | main | organization-wide build and evidence doctrine | operational snapshot at `skill-lib/` |
+| `The-Interdependency/metapat` | `34d954aa1e2092e615b03a180500f6b6977f501e` | main | semantic authority (Meta Energy Theory) | canon view `libs/metapat/`; research `research/metapat/` |
+| `The-Interdependency/ucns` | `1975fe70cf4e0826a8020c2da3047569e277af64` | main | geometry and mathematical representation | canon view `libs/ucns/`; research `research/ucns/` |
+| `The-Interdependency/edcm` | `7951ca32ba0f2494dc68ff9b7f6a80151918a56d` | main | measurement and text-gonol construction | canon view `libs/edcm/`; research `research/edcm/` |
+| `The-Interdependency/pcea` | `4d2c581448b97bfb71da92b35487e74e6e3bcedc` | main | prime circle encryption algorithm | canon view `libs/pcea/`; research `research/pcea/` |
+| `The-Interdependency/ptcna` | `97abdd1bbda61a68e0aac8595a32a3cb0ce73487` | main | prime tensor circled neural architecture | canon view `libs/ptcna/`; research `research/ptcna/` |
+| `The-Interdependency/epac` | `hmmm` | — | stack-local emerging research; no independent source repository exists yet | active candidate `research/epac/`; `libs/epac/` unpopulated |
+
+The imported `libs/` trees are the complete tracked working trees of their source
+repositories at the pinned commits, produced from Git trees / `git archive` contents.
+VCS metadata, virtualenvs, caches, and untracked files are excluded.
 
-Each `research/` snapshot is the complete tracked working tree of its source repository at
-the pinned commit, produced with `git archive HEAD`. VCS data, virtualenvs, caches, and
-untracked files are excluded by construction.
+## Research base records
 
-## License status at snapshot commits
+Each established `research/<repo>/` workspace carries a `BASE.json` with:
+
+- owning repository;
+- exact source commit;
+- matching `libs/<repo>/` canon path;
+- authority owner;
+- standing `stack-local-research`.
+
+Use that record before interpreting or extending work in the workspace.
+
+## License status at pinned commits
 
 | Repository | License file |
 |---|---|
@@ -34,33 +62,43 @@ untracked files are excluded by construction.
 | edcm | MPL-2.0 (`LICENSE`) |
 | pcea | present (`LICENSE`) |
 | ptcna | present (`LICENSE`) |
-| epac | placeholder — no license yet |
+| epac | no independent repository/license yet |
 
 ## Non-transfer boundaries
 
-- `authority_transfer: false` — snapshots do not gain authority over the source repositories.
-- `proof_status_transfer: false` — no proof/theorem status transfers into this aggregation.
+- `authority_transfer: false` — imported canonical views do not gain authority over their owners.
+- `proof_status_transfer: false` — no proof/theorem status transfers through stack composition.
 - `measurement_status_transfer: false` — no measurement/empirical validity transfers.
-- `semantic_mapping: external-provenance` — canonical meaning remains owned by the source
-  repositories; this repo only pins identities.
-- `research/` snapshots are **not the source of truth**. Edit the canonical repositories
-  first, then refresh this snapshot.
+- `semantic_mapping: external-provenance` — canonical meaning remains owned by source repositories.
+- `research/` is explicitly noncanonical stack-local work.
+- `libs/` is read-only by contract and is refreshed only from an owning repository at an exact commit.
 
 ## Refresh procedure
 
 For each pinned repository, from a clean checkout at the desired commit:
 
 ```bash
-git -C <checkout> archive <commit> | tar -x -C research/<name>/
+rm -rf libs/<name>/*
+git -C <checkout> archive <commit> | tar -x -C libs/<name>/
 ```
 
-Then update this file and `stack-manifest.json`, recompute the work-graph digest, and
-commit with a message citing the new source commit SHAs.
+Then update this file, `stack-manifest.json`, and `research/<name>/BASE.json`; recompute
+the work-graph digest; and commit with the new source commit SHA.
+
+Do not edit `libs/<name>/` to create a canonical change. Route the change to the owning
+repository, merge it there, then refresh the pinned view.
+
+## Graduation boundary
+
+A project born in stack (currently EPAC; AHBG follows its own workspace) may eventually
+become an independent repository. Graduation is not accomplished by copying its research
+tree into `libs/`. First create the owning repository and preserve provenance; after the
+new repository becomes authoritative and a commit is pinned, populate its `libs/<name>/`
+view from that authority.
 
 ## hmmm
 
-- ucns has no LICENSE file at snapshot commit `1975fe7`; its licensing terms need to be
-  resolved at the source repository.
-- epac has no source repository yet; its placeholder carries no doctrine until one exists.
-- `libs/`, `backend/`, and `frontend/cli/` are intentional empty scaffolds reserved for
-  later stack integration work.
+- UCNS has no LICENSE file at pinned commit `1975fe7`; licensing terms need resolution at source.
+- EPAC has no independent source repository or populated canonical `libs/epac/` view yet.
+- `skill-lib/` remains a special operational snapshot at stack root rather than following the
+  ordinary `libs/` + `research/` pair.