Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions .agents/skills/README.md
Original file line number Diff line number Diff line change
@@ -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.
11 changes: 11 additions & 0 deletions .agents/skills/stack-update/PROVENANCE.json
Original file line number Diff line number Diff line change
@@ -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"
}
156 changes: 156 additions & 0 deletions .agents/skills/stack-update/SKILL.md
Original file line number Diff line number Diff line change
@@ -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.
Comment on lines +1 to +3

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Record the source identity of the vendored skill

This new repo-local skill is described as newer doctrine than the pinned skill-lib/ snapshot, but neither its frontmatter nor any adjacent provenance record identifies the exact source repository commit or a non-transfer boundary. A repo-wide search finds only references to the local path, so agents cannot verify which canonical skill revision governs structural updates or detect local drift from that source.

AGENTS.md reference: AGENTS.md:L21-L22

Useful? React with 👍 / 👎.

---

# 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.
37 changes: 37 additions & 0 deletions .github/workflows/stack-consistency.yml
Original file line number Diff line number Diff line change
@@ -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'
Comment on lines +10 to +12

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Reject unpinned edits to canonical library snapshots

When a PR edits only a tracked file under libs/**, this path starts the consistency job, but the invoked checker never examines the Git diff or any library contents. After the current UCNS baseline failure is repaired, a silent edit to a pinned canonical snapshot will therefore pass unchanged manifests and BASE records, defeating the read-only boundary this workflow is meant to enforce.

AGENTS.md reference: AGENTS.md:L9-L10

Useful? React with 👍 / 👎.

- '.agents/skills/stack-update/**'

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Trigger the gate for vendored-skill index changes

When a PR changes only .agents/skills/README.md, neither this pull-request path list nor the equivalent push list starts the consistency job, even though check_stack_update_skill_provenance() explicitly reads that file and would reject a missing or mismatched source commit/blob. The newly added human provenance index can therefore drift from PROVENANCE.json without the intended gate running; include .agents/skills/README.md in both path filters.

AGENTS.md reference: AGENTS.md:L21-L22

Useful? React with 👍 / 👎.

- '.github/workflows/stack-consistency.yml'
Comment on lines +10 to +14

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Run the structural gate for root emerging-project changes

When a PR changes only ahbg/**—including deleting or moving that root-level emerging participant—its workspace-specific workflows may run, but this consistency workflow is not created because the path list covers only research/**, libs/**, and named projection files. A structural AHBG change that omits the required manifest and architecture updates can therefore merge without the new fail-closed gate ever executing.

AGENTS.md reference: AGENTS.md:L24-L27

Useful? React with 👍 / 👎.

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
35 changes: 34 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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:
Comment on lines +33 to +34

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Make the required graduation skill resolvable

For extraction or graduation work in a clean checkout, this new mandatory instruction cannot be followed: a repo-wide search finds no project-incubation-graduation/SKILL.md under .agents/, the pinned skill-lib/, or any other repository path, only references to its name. Lifecycle updates therefore depend on unspecified external state instead of the exact reproducible doctrine required by the gate; vendor a provenance-bound copy or identify an available pinned path.

AGENTS.md reference: AGENTS.md:L33-L34

Useful? React with 👍 / 👎.

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,
Expand Down Expand Up @@ -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
Expand All @@ -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.
46 changes: 38 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/
Expand All @@ -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
Expand All @@ -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
```
Expand Down Expand Up @@ -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
Expand All @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -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
Expand All @@ -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
Expand Down
Loading
Loading