-
Notifications
You must be signed in to change notification settings - Fork 0
feat: make structural stack updates fail closed #36
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
53fdff6
78ea3a3
46496a0
c5ed35e
c69b4e7
64f8eec
b02d515
0e4a3f8
2415ed2
627eeab
759f300
7c95852
eaf6662
2c99df0
8c9b79a
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| 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. |
| 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" | ||
| } |
| 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. | ||
| --- | ||
|
|
||
| # 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. | ||
| 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
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
When a PR edits only a tracked file under AGENTS.md reference: AGENTS.md:L9-L10 Useful? React with 👍 / 👎. |
||
| - '.agents/skills/stack-update/**' | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
When a PR changes only AGENTS.md reference: AGENTS.md:L21-L22 Useful? React with 👍 / 👎. |
||
| - '.github/workflows/stack-consistency.yml' | ||
|
Comment on lines
+10
to
+14
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
When a PR changes only 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 | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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: | ||
|
Comment on lines
+33
to
+34
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
For extraction or graduation work in a clean checkout, this new mandatory instruction cannot be followed: a repo-wide search finds no 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, | ||
|
|
@@ -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. | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 👍 / 👎.