Merge pull request #36 from The-Interdependency/feat/stack-update-guard

feat: make structural stack updates fail closed

Author: erinepshovel-code

.agents/skills/README.md

@@ -0,0 +1,12 @@
+# Vendored agent skills
+
+This directory contains repo-local consumed copies of canonical skills from
+`The-Interdependency/skill-lib`.
+
+Installed subset:
+
+- `stack-update` — source `The-Interdependency/skill-lib@a7b95f891d2e88c62e61524dc52a2e1577c9983d`, path `stack-update/SKILL.md`, source blob `a1e914893fa047e28d039050395937a1cf6e0138`.
+
+Canonical doctrine remains in `skill-lib`; vendoring does not transfer authority.
+Structural stack changes must follow `.agents/skills/stack-update/SKILL.md` and pass
+`python tools/check_stack_consistency.py` before merge.

.agents/skills/stack-update/PROVENANCE.json

@@ -0,0 +1,11 @@
+{
+  "schema": "the-interdependency.vendored-skill-provenance",
+  "version": "1.0.0",
+  "skill": "stack-update",
+  "source_repository": "The-Interdependency/skill-lib",
+  "source_commit": "a7b95f891d2e88c62e61524dc52a2e1577c9983d",
+  "source_path": "stack-update/SKILL.md",
+  "source_blob_sha": "a1e914893fa047e28d039050395937a1cf6e0138",
+  "authority_transfer": false,
+  "relation": "repo-local consumed copy; canonical doctrine remains in source repository"
+}

.agents/skills/stack-update/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: stack-update
+description: Fail-closed update protocol for The-Interdependency/stack. Load this when a stack change adds, moves, extracts, graduates, renames, removes, or changes the authority, relation, source identity, or placement of a participant, research workspace, libs pin, BASE record, stack manifest entry, or architecture description; when stack-manifest.json, STACK_MANIFEST.md, README.md, or research BASE.json files may drift from one another; or when validating that a structural stack change is complete before commit or merge.
+---
+
+# stack-update — change the stack as one coherent transaction
+
+Use this procedural skill for structural changes to `The-Interdependency/stack`.
+It specializes `interdependent-work-graph`; it does not replace that skill or
+`project-incubation-graduation`.
+
+## Core contract
+
+A stack change that alters **identity, ownership, authority, relation, lifecycle,
+or placement** is incomplete until every affected authority/provenance projection
+agrees and the deterministic stack-consistency checker passes.
+
+```text
+structural mutation
+  -> classify affected authority and relations
+  -> update owning source and stack projections
+  -> recompute machine identity
+  -> validate local + cross-boundary consistency
+  -> commit only when coherent
+```
+
+Location never creates authority. A successful move, import, extraction, or test
+run does not itself update ownership, canon, proof status, measurement validity,
+or graduation standing.
+
+## Trigger / non-trigger
+
+Load this skill when a change touches any of these surfaces or their meaning:
+
+- `libs/<repo>/` pins or imported canonical views;
+- `research/<workspace>/` creation, deletion, rename, extraction, or lifecycle;
+- `research/*/BASE.json` provenance or authority;
+- `stack-manifest.json` / `STACK_MANIFEST.md` participants, authorities, relations,
+  boundaries, or work-graph digest;
+- root architecture descriptions in `README.md` or `AGENTS.md`;
+- an emergent project moving toward or away from independent-repository authority.
+
+Do not load it for an ordinary implementation edit whose owning repository,
+workspace, authority, manifest identities, and architecture relations do not change.
+
+## Required companion skills
+
+1. Load `interdependent-work-graph` for every structural stack mutation.
+2. Load `project-incubation-graduation` when extraction, release, reconsumption,
+   graduation, or implementation-authority transition is involved.
+3. Load `the-interdependency` for organization workflow and GitHub hygiene.
+4. Consult current METAPAT only when the change requires choosing a new conceptual
+   distinction or authority relation rather than implementing an already-fixed one.
+
+## Workflow
+
+1. **Freeze the starting identity.** Record the exact stack commit and every
+   producer/source commit whose authority can affect the change.
+2. **Classify the mutation.** Mark each affected item as one or more of:
+   `identity`, `authority`, `relation`, `placement`, `lifecycle`, `pin`, `projection`.
+3. **Resolve edit ownership.** Change a claim at its owning source. Never repair a
+   producer-owned defect by shadowing it in a consumer or by editing `libs/`.
+4. **Compute the update closure.** Inspect at minimum:
+   `stack-manifest.json`, `STACK_MANIFEST.md`, root `README.md`, root `AGENTS.md`,
+   the affected `research/*/BASE.json`, relevant local README/docs, and CI/checkers.
+   Update every projection whose statement became false because of the mutation.
+5. **Remove superseded claims.** A newly separated owner requires the prior owner to
+   stop claiming that responsibility in every stack-level authority projection.
+   Do not merely add the new owner alongside stale text.
+6. **Preserve lifecycle standing.** Extraction is not graduation. Stack-local work
+   remains noncanonical until its governing graduation gates complete and stack
+   reconsumes the released independent artifact where required.
+7. **Recompute machine identity.** Recompute `work_graph_sha256` exactly from the
+   versioned manifest contract after any hashed field changes. Never hand-wave or
+   copy an old digest.
+8. **Run deterministic consistency validation.** In stack, run:
+
+   ```bash
+   python tools/check_stack_consistency.py
+   ```
+
+   Treat any error as a blocked structural update, not a documentation warning.
+9. **Run affected behavioral gates.** Execute repository/workspace-local tests and
+   at least one cross-boundary check for changed producer/consumer relations.
+10. **Commit the transaction.** The structural mutation and its required projections
+    belong in one coherent PR/merge sequence. If a necessary authority is unavailable,
+    preserve the boundary as `hmmm`; do not guess it into consistency.
+
+## Deterministic checker contract
+
+A consuming stack checker should fail closed for at least:
+
+- a `work_graph_sha256` that does not reproduce from the declared manifest fields;
+- disagreement between machine-readable and human-readable repository authority;
+- direct tracked edits to `libs/` presented as stack-owned canon;
+- an affected `BASE.json` whose source repository/commit conflicts with the pinned
+  source identity it claims to derive from;
+- an emergent stack-local component whose authority separation is declared locally
+  while stack-level authority text still assigns that responsibility to its former owner;
+- lifecycle language that treats extraction as graduation;
+- a structural update that changes one required projection but omits another.
+
+The checker validates coherence, not truth of scientific or semantic claims. Those
+remain owned by their proper repositories and evidence.
+
+## Output shape
+
+When this skill is active, report:
+
+```markdown
+## Stack transaction
+- start identity:
+- mutation class:
+- affected authority / relations:
+- files changed:
+
+## Validation
+- stack consistency:
+- local gates:
+- cross-boundary gate:
+
+## Standing
+- canon / research / extracted / graduated:
+- hmmm:
+```
+
+## Usage guidance
+
+Before moving or separating a stack component, run the checker once **before** the
+change to establish the current baseline, make the structural edit and all required
+projection updates, then run it again. A pre-existing failure is evidence to classify;
+it is not permission to add another inconsistency.
+
+Example: moving English Gonol Construction out of EDCM requires the new workspace and
+its provenance **and** removal of `text-gonol construction` from EDCM's stack-level
+authority statement, corresponding manifest/work-graph updates, digest regeneration,
+and the affected English Gonol + EDCM checks.
+
+## Anti-patterns
+
+- Moving code first and treating manifest/docs repair as optional cleanup.
+- Updating `stack-manifest.json` but not `STACK_MANIFEST.md`, or vice versa.
+- Adding a new authority statement without removing the superseded one.
+- Editing `libs/<repo>/` to make a stack-local inconsistency disappear.
+- Reusing a stale work-graph digest after changing hashed fields.
+- Calling an extracted project graduated because the new repository exists.
+- Making CI green by widening `PYTHONPATH` or weakening checks instead of repairing
+  ownership/provenance drift.
+
+## hmmm
+
+- The first stack checker is intentionally conservative: it can prove declared
+  projections agree, but it cannot infer every semantic responsibility from source code.
+- Future schema revisions may carry explicit typed stack-local component records and
+  edge lists so more structural obligations can be checked without text comparisons.
+- A checklist that never fails a build eventually becomes wall decoration.

.github/workflows/stack-consistency.yml

@@ -0,0 +1,37 @@
+name: stack-consistency
+
+on:
+  pull_request:
+    paths:
+      - 'stack-manifest.json'
+      - 'STACK_MANIFEST.md'
+      - 'README.md'
+      - 'AGENTS.md'
+      - 'research/**'
+      - 'libs/**'
+      - 'tools/check_stack_consistency.py'
+      - '.agents/skills/stack-update/**'
+      - '.github/workflows/stack-consistency.yml'
+  push:
+    branches: [main]
+    paths:
+      - 'stack-manifest.json'
+      - 'STACK_MANIFEST.md'
+      - 'README.md'
+      - 'AGENTS.md'
+      - 'research/**'
+      - 'libs/**'
+      - 'tools/check_stack_consistency.py'
+      - '.agents/skills/stack-update/**'
+      - '.github/workflows/stack-consistency.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  consistency:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Verify stack authority and provenance projections
+        run: python tools/check_stack_consistency.py

AGENTS.md

@@ -10,6 +10,9 @@ projects may later graduate into their own repositories.
   inside stack; canonical edits happen in the owning repository.
 - `research/<repo>/` is current stack-local research against an exact pinned base. It is
   not canon merely because it is in stack.
+- `research/english-gonol/` is a distinct stack-local English lexical/gonol construction
+  component. UCNS owns consumed geometry; EDCM may evaluate outputs but does not define
+  the English Gonol construction.
 - root-level emerging projects such as `ahbg/` may be close to external repo-hood; root
   placement does not transfer authority from their inputs.
 - `STACK_MANIFEST.md` and `stack-manifest.json` own stack-level participant provenance.
@@ -18,6 +21,27 @@ projects may later graduate into their own repositories.
 - `skill-lib/` is the currently pinned operational skill snapshot; exact newer doctrine
   may be bound separately only when its provenance and non-transfer boundary are explicit.
 
+## Structural update gate
+
+Before adding, moving, separating, extracting, graduating, renaming, removing, or
+changing the authority/relation/pin of a stack participant or research workspace, load:
+
+```text
+.agents/skills/stack-update/SKILL.md
+```
+
+Also resolve the applicable `interdependent-work-graph` doctrine and, for lifecycle
+transitions, `project-incubation-graduation`. Structural changes are one transaction:
+update every affected machine/human authority projection, remove superseded ownership
+claims, recompute the work-graph digest, and pass:
+
+```bash
+python tools/check_stack_consistency.py
+```
+
+Do not treat moved code, passing local tests, or a new repository as sufficient evidence
+that stack authority/provenance records are current.
+
 ## Fresh-making boundary
 
 PostgreSQL on the VM is the single production state authority for derivation specs,
@@ -50,6 +74,12 @@ namespace is deprecated and removed; use `stackctl fresh ...`.
 
 ## Checks
 
+Structural stack consistency:
+
+```bash
+python tools/check_stack_consistency.py
+```
+
 Fresh-making/backend checks that can run without PostgreSQL:
 
 ```bash
@@ -65,13 +95,16 @@ PostgreSQL integration checks require an explicitly disposable database. A skipp
 integration check is `hmmm`, not a pass.
 
 AHBG/Grok has its own local suites under `ahbg/grok/`; run those when touching that
-workspace. Do not claim root manifest-check tooling that is not present in this branch.
+workspace. The root stack-consistency checker verifies declared authority/provenance
+coherence; it does not replace workspace behavioral tests.
 
 ## hmmm
 
 - Concrete VM PostgreSQL/auth/service-account/storage and backup-mount acceptance remains
   unobserved until checked on the VM.
 - Organization aggregate and website-projection derivation specs are not yet registered.
+- English Gonol Construction has distinct stack-local authority but has not yet gained an
+  independent repository/release authority boundary.
 - The complete root `skill-lib/` snapshot refresh remains separate because the current
   provenance-bound fresh-making doctrine is newer than the local generator snapshot.
 - Project graduation automation remains unimplemented.

README.md

@@ -20,6 +20,7 @@ For repositories with an independent authority:
 ```text
 stack/
 ├── skill-lib/               # operational pinned snapshot of org build/evidence doctrine
+├── .agents/skills/          # repo-local consumed skills; stack-update guards structural changes
 ├── libs/                    # manifest-pinned canonical repository views; do not edit
 │   ├── metapat/
 │   ├── ucns/
@@ -31,7 +32,8 @@ stack/
 ├── 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
+│   ├── english-gonol/       # English lexical/gonol construction; distinct from EDCM
+│   ├── edcm/                # current EDCM measurement research + BASE.json
 │   ├── pcea/                # current PCEA research + BASE.json
 │   ├── ptcna/               # current PTCNA research + BASE.json
 │   ├── epac/                # extracted candidate remains forge-side until graduation completes
@@ -41,6 +43,8 @@ stack/
 ├── backend/                 # PostgreSQL-backed durable fresh-making control plane
 ├── frontend/
 │   └── cli/                 # human control/status surface for backend
+├── tools/
+│   └── check_stack_consistency.py # deterministic authority/provenance drift gate
 ├── STACK_MANIFEST.md        # human-readable provenance and boundary record
 └── stack-manifest.json      # machine-readable work graph
 ```
@@ -68,6 +72,27 @@ cat research/ucns/BASE.json
 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`.
 
+English Gonol Construction is a separated stack-local component at
+`research/english-gonol/`. UCNS owns its consumed geometry. English Gonol owns the
+English text-domain construction candidate. EDCM may evaluate those outputs but does
+not define the construction.
+
+### Change stack structure
+
+Any change that alters a participant, pin, authority, relation, research workspace,
+extraction/graduation standing, `BASE.json`, or architecture projection must load the
+`stack-update` skill and finish as one coherent stack transaction.
+
+Run the deterministic gate before and after the mutation:
+
+```bash
+python tools/check_stack_consistency.py
+```
+
+A structural change is not complete merely because moved code or local tests pass. The
+machine manifest, human manifest, affected base records, architecture description, and
+work-graph digest must agree before merge.
+
 ### Compose something new
 
 New cross-project work may be born in stack. It does not inherit the authority of its
@@ -76,11 +101,13 @@ coherent enough to graduate, create its independent repository, preserve provena
 package/release it, then let stack consume the released project rather than a hidden
 stack-local implementation.
 
-EPAC and psychsocio metafauna are currently in this pre-graduation state. EPAC
-has an independent extracted repository, but extraction is not graduation: its
-forge research remains here until EPAC completes its release, downstream
-reconsumption, and authority-transition gates. From Photons to the Macroverse is
-also stack-local pre-graduation research.
+English Gonol Construction is currently a distinct stack-local research component,
+separated from EDCM but not independently graduated.
+EPAC and psychsocio metafauna are currently in this pre-graduation state.
+EPAC is further along: it has an independent extracted repository, but extraction is not
+graduation, so its forge research remains here until EPAC completes its release,
+downstream reconsumption, and authority-transition gates. From Photons to the Macroverse
+is also stack-local pre-graduation research.
 
 ### Make derived artifacts fresh without depending on hosted CI
 
@@ -122,7 +149,8 @@ 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.
+source commit in the message. Run `python tools/check_stack_consistency.py` before
+merge.
 
 ## Boundaries
 
@@ -132,7 +160,7 @@ source commit in the message.
   populated only from an owning canonical repository at an exact commit.
 - proof, measurement, semantic, empirical, and certification standing do not transfer
   merely because projects are composed in stack.
-- `backend/` may coordinate an owning repository but does not acquire that repository's
+- backend may coordinate an owning repository but does not acquire that repository's
   authority.
 - PostgreSQL owns orchestration/freshness evidence, not repository artifacts or canon.
 - executor success alone cannot establish freshness; the declared verifier and accepted
@@ -147,6 +175,8 @@ source commit in the message.
   `libs/` + `research/` pair.
 - The exact graduation automation from stack-local project to independent repo + package
   is not yet implemented.
+- English Gonol Construction has distinct stack-local authority but has not yet gained an
+  independent repository/release authority boundary.
 - Actual VM PostgreSQL/service-account/storage state and the independent backup device
   remain deployment observations until inspected on the VM.
 - A GitHub-hosted executor remains optional and unimplemented; VM-local execution is the