From 0fd3cf574043b0f402329ecbbc9840df24c52997 Mon Sep 17 00:00:00 2001 From: empea-careercriminal Date: Thu, 4 Jun 2026 17:08:38 +0200 Subject: [PATCH 1/5] Fix .invariants references to starter kit and plural dotfile name. Rename invariance-framework.md to invariants-framework.md, replace .invariance with .invariants across handbook/skills/llms.txt, point upstream links at boorich/.invariants-starter-kit and GitHub Pages landing, and replace invariance.html with a redirect to the hosted site. --- .github/CODEOWNERS | 4 +- AGENTS.md | 6 +- README.md | 2 +- invariants/agent-era-invariants.md | 4 +- invariants/engineering-invariants.md | 4 +- invariants/invariance-framework.md | 60 -- invariants/invariance.html | 890 ------------------ invariants/invariants-framework.md | 69 ++ invariants/invariants.html | 32 + languages/daml/architect.md | 12 +- languages/daml/developer.md | 2 +- languages/go/architect.md | 12 +- languages/python/architect.md | 4 +- languages/rust/architect.md | 10 +- languages/solidity/architect.md | 12 +- languages/typescript/architect.md | 10 +- languages/zig/architect.md | 10 +- llms.txt | 8 +- operating-model/collaborator-statement.md | 2 +- operating-model/mcp-and-llm-txt.md | 6 +- operating-model/model-and-tool-selection.md | 2 +- references/sources.md | 14 +- skills/chainsafe-go-architect/SKILL.md | 10 +- skills/chainsafe-rust-architect/SKILL.md | 6 +- skills/chainsafe-solidity-architect/SKILL.md | 2 +- .../chainsafe-typescript-architect/SKILL.md | 6 +- skills/chainsafe-zig-architect/SKILL.md | 6 +- workflows/repo-and-ci-setup.md | 2 +- 28 files changed, 179 insertions(+), 1028 deletions(-) delete mode 100644 invariants/invariance-framework.md delete mode 100644 invariants/invariance.html create mode 100644 invariants/invariants-framework.md create mode 100644 invariants/invariants.html diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 7a85d6a..90fc645 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -17,8 +17,8 @@ /README.md @kalambet /.github/CODEOWNERS @kalambet -# invariants — `.invariance` pointer page is owned by its upstream maintainer. -/invariants/invariance-framework.md @boorich @kalambet +# invariants — `.invariants` pointer page is owned by its upstream maintainer. +/invariants/invariants-framework.md @boorich @kalambet # workflows — pointer pages into ChainSafe/infrastructure-general are # owned by the Head of Infra alongside the curator. diff --git a/AGENTS.md b/AGENTS.md index 90623f6..56e7fb5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,9 +11,9 @@ You are an AI agent (Claude Code, Cursor, Continue, or other) operating against ## Repo map - `operating-model/` — operator/agent contract, gates, escalation, model and tool selection, MCP and `llms.txt`, memory conventions. Load relevant pages before any non-trivial work. -- `invariants/` — the non-negotiables. Engineering invariants, deep links into Martin Maurer's `.invariance` framework, agent-era invariants (no silent edits, no fabricated APIs, no committed secrets). +- `invariants/` — the non-negotiables. Engineering invariants, deep links into Martin Maurer's `.invariants` framework, agent-era invariants (no silent edits, no fabricated APIs, no committed secrets). - `workflows/` — PR authoring (delegates to the `chainsafe-research-plan-implement` skill), code review (operator-reviewing-agent and agent-reviewing-PR modes), repo & CI setup, testing & QA, infrastructure & DevOps (deep links into `ChainSafe/infrastructure-general`), incident response, release & deploy. -- `languages//` — for each of Go, Rust, TypeScript, Solidity, Daml, Python, Zig: `architect.md`, `developer.md`, `reviewer.md`, plus shared `idioms.md` and `gotchas.md`. Architect pages deep-link into `.invariance`. +- `languages//` — for each of Go, Rust, TypeScript, Solidity, Daml, Python, Zig: `architect.md`, `developer.md`, `reviewer.md`, plus shared `idioms.md` and `gotchas.md`. Architect pages deep-link into `.invariants`. - `references/` — attribution, source pointers, contributors. - `skills/` — packaged Anthropic Skills authored via `skill-creator`. Discoverable via `chainsafe.io/llms.txt` and via direct paths in this repo. - `VISION.md` — ChainSafe mission, vision, and core values (company-wide). Read for org-wide context; not load-bearing for most agent tasks. @@ -27,7 +27,7 @@ When picking up a task, load in this order: 2. `operating-model/collaborator-statement.md` (contract). 3. `operating-model/gates-and-escalation.md` (when to stop). 4. The most specific page for the task: a language role page, a workflow page, or a packaged skill in `skills/`. -5. Any external canonical source the chosen page deep-links into (`.invariance`, `infrastructure-general`) — fetch those targets, do not paraphrase from memory. +5. Any external canonical source the chosen page deep-links into (`.invariants`, `infrastructure-general`) — fetch those targets, do not paraphrase from memory. Do not load everything by default. Pull the minimum needed for the task. Skills in `skills/` are scoped on purpose; prefer them when one matches. diff --git a/README.md b/README.md index d09baf5..4272aed 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ The premise: engineering practices are a competitive asset, AI agents are now fi The structure is: - **`operating-model/`** — the operator/agent contract. How a human and an AI collaborator share responsibility for an output. Read this first. -- **`invariants/`** — the non-negotiables. Engineering invariants, the `.invariance` framework (deep-linked, not duplicated), and agent-era invariants. +- **`invariants/`** — the non-negotiables. Engineering invariants, the `.invariants` framework (deep-linked, not duplicated), and agent-era invariants. - **`workflows/`** — PR authoring, code review, repo & CI setup, testing & QA, infrastructure & DevOps (deep-linked into `ChainSafe/infrastructure-general`), incident response, release & deploy. - **`languages/`** — opinionated guidance per language ecosystem (Go, Rust, TypeScript, Solidity, Daml, Python, Zig) split into three roles: architect, developer, reviewer. - **`references/`** — attribution, source pointers, contributors. diff --git a/invariants/agent-era-invariants.md b/invariants/agent-era-invariants.md index 52b1018..54c6b86 100644 --- a/invariants/agent-era-invariants.md +++ b/invariants/agent-era-invariants.md @@ -22,7 +22,7 @@ These extend the [Engineering Invariants](./engineering-invariants.md) — they **Why.** Fabrication is the failure mode that costs the most to detect. It looks right; it sounds plausible; it compiles in some cases. The operator only catches it when the runtime trips or the missing thing is searched for and not found — both of which can happen days after the change ships. -**How it's checked.** The agent verifies references before naming them (file exists, function is defined, page is in the handbook). For external sources (`.invariance`, `infrastructure-general`), the agent fetches the target rather than paraphrasing from training. CI link checker catches broken external references. +**How it's checked.** The agent verifies references before naming them (file exists, function is defined, page is in the handbook). For external sources (`.invariants`, `infrastructure-general`), the agent fetches the target rather than paraphrasing from training. CI link checker catches broken external references. **Override.** None. The operator cannot ask the agent to fabricate. If the operator says "just make something up that looks right," the agent refuses and escalates. @@ -111,4 +111,4 @@ No single layer is sufficient. Agents can be misconfigured; CI can have gaps; re - [`engineering-invariants.md`](./engineering-invariants.md) — the general engineering invariants these extend. - [`../operating-model/collaborator-statement.md`](../operating-model/collaborator-statement.md) — the contract these invariants are the rule-form of. Refusal cases appear there as policy and here as invariants. - [`../operating-model/gates-and-escalation.md`](../operating-model/gates-and-escalation.md) — gates can be approved; these invariants cannot, except for the explicit-override cases noted above. -- [`./invariance-framework.md`](./invariance-framework.md) — Martin Maurer's `.invariance` framework for architectural invariants. Domain-specific complement to this page. +- [`./invariants-framework.md`](./invariants-framework.md) — Martin Maurer's `.invariants` framework for architectural invariants. Domain-specific complement to this page. diff --git a/invariants/engineering-invariants.md b/invariants/engineering-invariants.md index 51022c5..680d122 100644 --- a/invariants/engineering-invariants.md +++ b/invariants/engineering-invariants.md @@ -74,12 +74,12 @@ This page is the testable subset of the [General Engineering Principles](../PRIN - **Not a license to bypass review.** Invariants and review are layered defenses, not alternatives. Both apply. - **Not absolute.** Overrides exist. They are logged in the PR with the override reason. Frequent override of the same invariant is a sign the invariant needs revision, not that the override is fine. -- **Not exhaustive.** Domain-specific invariants live elsewhere — the `.invariance` framework ([`./invariance-framework.md`](./invariance-framework.md)) is the canonical source for architectural invariants; language-specific invariants live in [`../languages//`](../languages/) reviewer pages. +- **Not exhaustive.** Domain-specific invariants live elsewhere — the `.invariants` framework ([`./invariants-framework.md`](./invariants-framework.md)) is the canonical source for architectural invariants; language-specific invariants live in [`../languages//`](../languages/) reviewer pages. ## Related - [`agent-era-invariants.md`](./agent-era-invariants.md) — additional invariants specific to agent-assisted work (no silent edits, no fabrication, no commits of secrets, etc.). -- [`invariance-framework.md`](./invariance-framework.md) — pointer page deep-linking into Martin Maurer's `.invariance` framework for architectural invariants. +- [`invariants-framework.md`](./invariants-framework.md) — pointer page deep-linking into Martin Maurer's `.invariants` framework for architectural invariants. - [`../operating-model/collaborator-statement.md`](../operating-model/collaborator-statement.md) — the operator-first contract these invariants operate under. - [`../PRINCIPLES.md`](../PRINCIPLES.md) — General Engineering Principles. The aspirational layer above these invariants; cultural principles that aren't testable live there. - [`../VISION.md`](../VISION.md) — company-wide mission, vision, and core values that PRINCIPLES.md flows from. diff --git a/invariants/invariance-framework.md b/invariants/invariance-framework.md deleted file mode 100644 index db7d4f7..0000000 --- a/invariants/invariance-framework.md +++ /dev/null @@ -1,60 +0,0 @@ -# The `.invariance` Framework - -For architecture and system-design invariants, this handbook does not re-derive a methodology. The canonical source is Martin Maurer's **`.invariance`** project. This page's job is to deep-link into it by intent, not to gesture at it as a separate resource to "go read." - -> **In one line:** Architecture invariants live in `.invariance`. This page is the navigation surface; the rules themselves live upstream. - -## Why we defer here - -`.invariance` is a multi-repo invariant convention authored by [@boorich](https://github.com/boorich). It is one of the strongest existing artifacts within ChainSafe for the question "how do we make architectural decisions consistent across products?" The handbook treats it as canonical for that question — duplicating its content here would create drift; the handbook's value here is in the *navigation*, not the substance. - -The deep-link map below is keyed by the question an agent or operator is trying to answer, so readers land on the exact upstream section they need. - -## Deep-link map - -The map is keyed by the question an agent or operator is trying to answer. Where the upstream `.invariance` repo lacks an anchor needed for clean linking, the convention is to request the anchor upstream rather than work around it with a deeper inline copy. - -### By question - -| If you are asking… | Go to (upstream `.invariance`) | -|---|---| -| What is an invariant in this framework? | `README.md` overview | -| How do I name an invariant? | Naming convention section | -| How do I make an invariant testable? | Testability section | -| What is the lifecycle of an invariant — proposal → approval → enforcement → retirement? | Lifecycle section | -| How is an invariant violation reported and triaged? | Violation reporting | -| How are invariants versioned and migrated? | Versioning section | -| How does `.invariance` interact with ADRs in product repos? | Cross-repo interaction | - -### By context - -Where the handbook deep-links into `.invariance` from elsewhere: - -| Handbook section | Upstream target | -|---|---| -| `languages//architect.md` (every architect role) | Per-language invariant section, e.g. concurrency invariants for the Rust architect, data-integrity invariants for the Daml architect | -| `workflows/pr-authoring.md` (ADR templates) | "Invariants impacted" template guidance | -| Reviewer skills — when a language reviewer needs to check whether an architectural invariant is violated | Reviewer-facing rules | - -## How to use this page - -- **As an agent:** before any architecture or system-design task, consult the by-question table above. Fetch the upstream `.invariance` content for the entries that apply. Do not paraphrase upstream content from your training; pull the actual file. -- **As an operator:** when reviewing an architectural proposal (ADR, design doc, system design), use the deep-link table to verify the proposal addresses the relevant invariants. The `languages//architect.md` pages cite specific invariants per language; this page is the meta-index. -- **As a contributor adding architectural content to this handbook:** do not duplicate `.invariance` rules in your page. Deep-link them. If the upstream rule you need is not anchorable cleanly, coordinate with [@boorich](https://github.com/boorich) to add the heading, then link. - -## Inline `.invariance`-derived rules (for trivial-lookup cases only) - -To keep agents from chasing the link for every minor question, a small set of `.invariance`-derived rules is restated inline. This list is kept short on purpose — anything beyond a one-liner belongs upstream, not here. - -*Which rules earn an inline restatement versus a link-only entry is coordinated with [@boorich](https://github.com/boorich). The bar is deliberately high: only genuinely one-line, frequently-needed rules are restated here; everything else stays upstream.* - -## Coordination - -[@boorich](https://github.com/boorich) is the maintainer of `.invariance` and the CODEOWNER for this pointer page (see [`../.github/CODEOWNERS`](../.github/CODEOWNERS)). Any change to the deep-link map or to the inline-rules section goes through him. Conversely, when the upstream repo restructures, the anchors here update — the pointer page is the contract between the handbook and the upstream repo. - -## Related - -- [`engineering-invariants.md`](./engineering-invariants.md) — general engineering invariants. `.invariance` is the domain-specific complement for architecture. -- [`agent-era-invariants.md`](./agent-era-invariants.md) — agent-specific invariants; orthogonal to `.invariance`. -- [`../languages/`](../languages/) — language-specific architect pages deep-link into `.invariance` per the by-context table above. -- [`../references/sources.md`](../references/sources.md) — full catalog of external canonical sources the handbook defers to. diff --git a/invariants/invariance.html b/invariants/invariance.html deleted file mode 100644 index efe0b98..0000000 --- a/invariants/invariance.html +++ /dev/null @@ -1,890 +0,0 @@ - - - - - -.invariance - - - - - - -
- - -
-
A convention for multi-repo integrity
-

.invariance

-

A dotfile that defines what must always remain true.

-

- Large projects span many repositories. Over time, they drift. Interfaces break silently. - Architectural vision dissolves into technical debt. .invariance is a lightweight - convention — one structured file per repo — that makes your project's non-negotiable conditions - explicit, machine-checkable, and human-readable. When an issue arrives, the cascade tells the - agent exactly what outcome to produce. No judgment required. -

-
- -
- -
-
The problem
-

Projects grow. Intent fades.

-

- When a project lives across six repositories, no single developer holds the full picture. - A change in one repo breaks an assumption in another. A refactor violates a protocol guarantee - nobody wrote down. The project still compiles. Tests still pass. But the architecture quietly - becomes something different from what was intended. -

- -
-
- 01 -
Descriptive, not prescriptive
-

Invariants are written as structured descriptions of conditions that must remain true — not as executable code or rules engines. Plain language. No special syntax.

-
-
- 02 -
Hierarchical by design
-

A root repo holds the project constitution. Each sub-repo holds its own local invariants and inherits from the apex. Both levels are evaluated independently.

-
-
- 03 -
Precise, not vague
-

The agent doesn't warn. It produces a verdict — BLOCKED, PROCEED TO TRIAGE, or CLOSE — determined entirely by which assertion was threatened and at what severity. The humans who wrote the assertions made the decision when they assigned the severity.

-
-
- 04 -
Forks are valid
-

A sub-repo that diverges from the root constitution isn't broken — it's forking. The system makes that explicit before it becomes invisible technical debt.

-
-
-
- -
- -
-
Lineage
-

Built on two established shoulders.

-

- This is not a new category invented from nothing. Two bodies of practice already address - parts of this problem. .invariance sits at their intersection — and fills - the gap neither covers. -

- -
- -
-
-
Architecture Decision Records
-
- Michael Nygard, 2011
- adr.github.io
- standard practice -
-
-
-

- ADRs capture why a decision was made — context, alternatives considered, consequences. They live alongside the code as an immutable historical record. Once written, an ADR is not modified; a new one supersedes it. The why: field in every .invariance assertion is an ADR in miniature. -

-

- ADRs document the past. They have no enforcement mechanism. An agent reading your ADRs learns the rationale but receives no instruction on what to do when a proposal threatens them. -

-
-
- -
+
- -
-
-
Architectural Fitness Functions
-
- Ford, Parsons, Kua — 2017
- Building Evolutionary Architectures
- ThoughtWorks -
-
-
-

- Fitness functions are automated, objective checks that verify whether a system still satisfies a declared architectural characteristic — coupling boundaries, dependency direction, performance thresholds. They run in CI like tests, but they measure architectural intent rather than functional correctness. The severity field and the cascade verdict are fitness function logic. -

-

- Fitness functions require executable code. They work well for structural concerns expressible as dependency graphs or import chains. They cannot evaluate semantic invariants — "all SDKs derive this identifier identically" is not a rule you can write in ArchUnit. -

-
-
- -
- -
-
-
.invariance
-
- natural language assertions
- semantic evaluation
- agent-native enforcement -
-
-
-

- The gap between ADRs and fitness functions is semantic intent — conditions that require understanding meaning, not just structure. With an LLM agent as the evaluator, natural language assertions are executable. The agent wakes up, loads the cascade, reads the actual source files, and matches each assertion against the proposal. No separate rules engine. No code to maintain. The dotfile is the enforcement. -

-

- fills: semantic invariants that static analysis cannot check, in a runtime where the evaluator already understands language. -

-
-
- -
-
- -
- -
-
How it works
-

One file. One agent. One verdict.

-

- The entire system is built on a simple loop: describe what must be true, check the codebase - against it, return a verdict. -

- -
-
- 01 — -
-
Define your invariants
-

Add a .invariance file to the root repo and each sub-repo. Write what must always hold, at what severity. The root file is the constitution — it captures cross-repo guarantees. Sub-repos capture their own.

-
-
-
- 02 — -
-
The agent indexes your code
-

At the start of each session, the entire codebase is chunked into a local vector database — a semantic mirror of what actually exists. The agent can verify invariants against real code, not just metadata. The index is ephemeral; it's rebuilt fresh every session.

-
-
-
- 03 — -
-
A change is proposed
-

A GitHub issue, a pull request, a refactor. The agent loads the cascade — root .invariance and the relevant sub-repo file — and scans every assertion. For each one: does this proposal threaten the claim? It reads the actual source files to decide, not just the issue text.

-
-
-
- 04 — -
-
The cascade returns a verdict
-

The severity of the threatened assertion determines the outcome. FROZEN means the claim must never change — any proposal touching it is blocked. VERSIONED means it can change with a migration plan. ADDITIVE means proceed. If no assertion is threatened, close.

-
-
-
- -
-

- On forks: If a sub-repo defines invariants that are incompatible with the root constitution, - this is not treated as an error. It is treated as a signal that this repo is diverging — - that it is becoming something different. Forks are legitimate. - The system makes them visible early, before they become invisible technical debt. - Mark it status: intentional-fork and move on. -

-
-
- -
- -
-
The verdict
-

A match statement, not a meeting.

-

- The agent doesn't decide — it pattern matches. The severity field in each assertion is the decision, - made once by the humans who wrote it. Every proposal that arrives after that is evaluated mechanically. -

- -
- // The entire enforcement logic, in full: - match threatened_assertion.severity {
- FROZEN => BLOCKED — cross-repo guarantee. Requires MAJOR version + coordinated migration. - VERSIONED => PROCEED TO TRIAGE — breaking change. Needs a documented migration path. - ADDITIVE => PROCEED — new behaviour. Existing consumers unaffected. - None => CLOSE — not a protocol concern. Implementor scope. - } -
- The outcome is exhaustive and unambiguous. The agent executes the match. - The maintainers who wrote the severity field made the decision. -
-
- -
-
-
- FROZEN - — any change forks the protocol -
-
-
- VERSIONED - — can change with a migration plan -
-
-
- ADDITIVE - — new surface, nothing breaks -
-
- -
- From the field -
A developer asked for configurable subscriber ID derivation.
-

- A third-party developer was pre-computing subscriber IDs using ethers.utils.id(address) - — keccak256 of the UTF-8 hex string. The SDK uses keccak256(encodePacked(address)) - — keccak256 of the ABI-encoded bytes. Different inputs, different hashes, different bytes32. - Subscriptions created on the backend were invisible to the SDK.

- Their proposal: add a { derivation: 'utf8' | 'abi-encoded' } config option. - Reasonable on the surface. The cascade disagreed. -

-
- Issue arrives on open-creator-rails.sdk
-   └─ load /.invariance
-      └─ subscriber_derivation_cross_sdk_consistency · FROZEN
-          "All SDKs derive subscriber bytes32 identically"
-          cascades_to: sdk/.invariance#identity_derivation
-                      unity/.invariance#identity_derivation
-   └─ load sdk/.invariance
-      └─ subscriber_identity_derivation · FROZEN
-          "subscriberToId uses keccak256(encodePacked(['address'], [addr]))"

- Two FROZEN assertions threatened → BLOCKED on configurable derivation
- Documentation improvement → ADDITIVE → PROCEED -
-
- The proposal was split: option A (pluggable derivation) BLOCKED — if both formats are valid in the TypeScript SDK, Unity clients and backend services using different formats will silently diverge. Options B and C (docs + dev-time warning) PROCEED — additive, nothing breaks. The developer got a precise answer with a path forward, not a wall. -
-
-
- -
- -
-
The file format
-

What a .invariance file looks like

-

- Deliberately simple. A YAML document that describes conditions, not code. - The root file defines the project constitution. Sub-repos inherit from it - and add their own scoped assertions. -

- -
- # /.invariance — root constitution - version: "1.0"
- scope: "My Protocol — Apex Invariants"
- authority: "TPM only — not agent-writable"

- asserts:
-   - id: identity_derivation_consistency
-     claim: "All SDKs derive identity bytes32 identically from wallet addresses"
-     severity: FROZEN
-     verify:
-       search: "identity derivation keccak256 encodePacked wallet"
-     cascades_to:
-       - "sdk-a/.invariance#identity_derivation"
-       - "sdk-b/.invariance#identity_derivation"
-     why: "Cross-SDK divergence causes silent failures at runtime."

-   - id: access_check_semantics
-     claim: "isActive means endTime > block.timestamp — always"
-     severity: FROZEN
-     why: "Any semantic change forks the protocol for every consumer." -
- -
- # sdk-a/.invariance — sub-repo assertions - inherits: "../.invariance"

- asserts:
-   - id: identity_derivation
-     claim: "identity() uses keccak256(encodePacked(['address'], [addr]))"
-     severity: FROZEN
-     verify:
-       search: "identity keccak256 encodePacked address"
-       in_file: "src/utils.ts"
-     why: "Must match all other SDKs exactly."

-   - id: active_filter_consumer_pattern
-     claim: "Active check uses !isTerminated && endTime > now — not one condition alone"
-     severity: VERSIONED
-     why: "Either condition alone silently misses valid or expired subscriptions."
-     note: "Currently FAILING — tracked in issue #24." -
-
- -
- -
-
Philosophy
-

A constitution, not a linter.

-

- Most tools manage what was built. .invariance manages - why it was built and what it must remain. The distinction matters especially - in early-stage projects, where the code is still changing but the conceptual vision - must stay anchored. -

-

- Once the invariants are written, all other documentation — specs, glossaries, architecture - diagrams — becomes descriptive. They follow implementation reality instead of trying to - govern it. The agent keeps them accurate. The invariants keep the agent honest. -

-

- The constitution defines what the system is allowed to become. - Not the other way around. -

-
- -
-

An open convention. Take it, use it, adapt it.

- .invariance / v0.1 -
-
- - - \ No newline at end of file diff --git a/invariants/invariants-framework.md b/invariants/invariants-framework.md new file mode 100644 index 0000000..1528728 --- /dev/null +++ b/invariants/invariants-framework.md @@ -0,0 +1,69 @@ +# The `.invariants` Framework + +For architecture and system-design invariants, this handbook does not re-derive a methodology. The canonical source is Martin Maurer's **`.invariants`** convention and optional reference workspace. This page's job is to deep-link into it by intent, not to duplicate it here. + +| Resource | URL | +|----------|-----| +| **Starter kit (repo)** | [github.com/boorich/.invariants-starter-kit](https://github.com/boorich/.invariants-starter-kit) | +| **Landing page** | [boorich.github.io/.invariants-starter-kit/](https://boorich.github.io/.invariants-starter-kit/) | +| **[vecs](https://github.com/boorich/vecs)** (code index CLI) | Used by the starter kit; optional for Level 1 dotfile-only adoption | + +> **In one line:** Architectural invariants live in **`.invariants`** dotfiles (plural). This page is the navigation surface; the convention, examples, and agent loop live in the starter kit. + +> **Filename:** **`.invariants`** — not `.invariance`. The dotfile is YAML; there is no special file terminator. + +## Why we defer here + +**`.invariants`** is a multi-repo dotfile convention ([@boorich](https://github.com/boorich)). It is one of the strongest existing artifacts within ChainSafe for the question "how do we make architectural decisions consistent across products?" The handbook treats the starter kit as canonical for that question — duplicating its content here would create drift; the handbook's value here is *navigation*, not substance. + +## Adoption depth + +| Level | What you do | Starter kit required? | +|-------|-------------|------------------------| +| **1** | `cp .invariants.example .invariants` in your repo | No | +| **2** | Apex + per-repo cascade (`inherits`, `cascades_to`) | No | +| **3** | `bash setup.sh` — vecs code index, `gh` triage, conformance agent | Yes — [repo](https://github.com/boorich/.invariants-starter-kit) | + +## Deep-link map + +Keyed by the question an agent or operator is trying to answer. Fetch upstream content; do not paraphrase from training. + +### By question + +| If you are asking… | Go to | +|---|---| +| What is the convention? | [Starter kit README](https://github.com/boorich/.invariants-starter-kit/blob/main/README.md) · [Landing page](https://boorich.github.io/.invariants-starter-kit/) | +| What does a dotfile look like? | [`.invariants.example`](https://github.com/boorich/.invariants-starter-kit/blob/main/.invariants.example) · Spec section on the [landing page](https://boorich.github.io/.invariants-starter-kit/#spec) | +| How are verdicts chosen? | [Conformance agent rule](https://github.com/boorich/.invariants-starter-kit/blob/main/.cursor/rules/conformance-agent.mdc) · [Verdict section](https://boorich.github.io/.invariants-starter-kit/#verdict) | +| How do I run the full loop locally? | [Try it](https://boorich.github.io/.invariants-starter-kit/#try) · `bash setup.sh` in the repo | +| Code vs markdown for agents? | README [Two layers](https://github.com/boorich/.invariants-starter-kit#two-layers-code-in-vecs-markdown-on-disk) · `·NAV` sentinels in `GLOSSARY.md` | +| Qdrant without Docker (macOS)? | [README — native install](https://github.com/boorich/.invariants-starter-kit#qdrant-without-docker-macos-power-users) | + +### By context + +| Handbook section | Upstream target | +|---|---| +| `languages//architect.md` (every architect role) | This pointer page + product-repo `.invariants` files | +| `workflows/pr-authoring.md` (ADR templates) | "Invariants impacted" — cite assertion `id` from the cascade | +| Reviewer / architect skills | [`invariants-framework.md`](./invariants-framework.md) before architecture tasks | + +## How to use this page + +- **As an agent:** Before architecture or system-design work, consult the by-question table. Pull files from the [starter kit repo](https://github.com/boorich/.invariants-starter-kit) or product `.invariants` dotfiles. Do not invent assertion ids or severities. +- **As an operator:** When reviewing an ADR or design, verify threatened claims against the cascade. PASS/FAIL belongs in reports — never in the dotfile. +- **As a contributor:** Do not duplicate `.invariants` rules in handbook pages. Deep-link here and upstream. Coordinate anchor changes with [@boorich](https://github.com/boorich). + +## What not to put in `.invariants` + +Issue numbers, "currently failing", fork labels, or temporary waivers. Forks are articulated in **conformance reports**, not in the dotfile. See the [landing page](https://boorich.github.io/.invariants-starter-kit/) and starter kit README. + +## Coordination + +[@boorich](https://github.com/boorich) maintains the upstream convention and is CODEOWNER for this pointer page (see [`../.github/CODEOWNERS`](../.github/CODEOWNERS)). When the starter kit restructures, update this map in the same PR. + +## Related + +- [`engineering-invariants.md`](./engineering-invariants.md) — general engineering invariants. `.invariants` is the complement for architecture. +- [`agent-era-invariants.md`](./agent-era-invariants.md) — agent-specific invariants; orthogonal to `.invariants`. +- [`../languages/`](../languages/) — architect pages defer to `.invariants` per the by-context table above. +- [`../references/sources.md`](../references/sources.md) — full catalog of external canonical sources. diff --git a/invariants/invariants.html b/invariants/invariants.html new file mode 100644 index 0000000..ffefc0f --- /dev/null +++ b/invariants/invariants.html @@ -0,0 +1,32 @@ + + + + + + + +.invariants — redirect + + + +

+ The canonical .invariants landing page moved to
+ boorich.github.io/.invariants-starter-kit/. +

+ + diff --git a/languages/daml/architect.md b/languages/daml/architect.md index 023391a..03dd123 100644 --- a/languages/daml/architect.md +++ b/languages/daml/architect.md @@ -1,12 +1,12 @@ # Daml Architect -Architectural guidance for Daml work at ChainSafe — primarily Canton applications including Super Validator and Featured App work. The architectural framework is `.invariance` ([pointer page](../../invariants/invariance-framework.md)); this page covers Daml-specific shaping. +Architectural guidance for Daml work at ChainSafe — primarily Canton applications including Super Validator and Featured App work. The architectural framework is `.invariants` ([pointer page](../../invariants/invariants-framework.md)); this page covers Daml-specific shaping. > **In one line:** Templates encode the contract. Signatories authorize. Choices are atomic. Upgrades are versioned packages, not patches. Every authorization decision is a security decision. -## Defer to `.invariance` for +## Defer to `.invariants` for -| Decision | `.invariance` section | +| Decision | `.invariants` section | |---|---| | Ledger-state invariants | Ledger invariants | | Authorization invariants | Authorization model | @@ -15,7 +15,7 @@ Architectural guidance for Daml work at ChainSafe — primarily Canton applicati ## Defer to the Canton docs for -`.invariance` above governs architectural *invariants*. Language and platform *semantics* — how Daml and Canton actually behave — are documented authoritatively at [docs.canton.network](https://docs.canton.network). Defer to it rather than re-deriving the language; it is a registered [canonical source](../../references/sources.md#canton-network-docs-daml-language--canton-platform). +`.invariants` above governs architectural *invariants*. Language and platform *semantics* — how Daml and Canton actually behave — are documented authoritatively at [docs.canton.network](https://docs.canton.network). Defer to it rather than re-deriving the language; it is a registered [canonical source](../../references/sources.md#canton-network-docs-daml-language--canton-platform). | Topic | Canton docs | |---|---| @@ -86,7 +86,7 @@ Every Daml ADR covers: - **Upgrade path.** Migration choices designed in. Version-numbered packages. - **Atomicity boundaries.** Which workflows are single-choice atomic; which are multi-choice with explicit intermediate states. - **Privacy commitments.** Which parties see what. -- **Invariants impacted.** Deep links into `.invariance`. +- **Invariants impacted.** Deep links into `.invariants`. ## Canton-specific considerations @@ -113,6 +113,6 @@ See [`../../workflows/infrastructure-and-devops.md`](../../workflows/infrastruct - [`developer.md`](./developer.md) — tooling, AI-assisted authoring (`daml-autopilot`), testing, and CI. - [`reviewer.md`](./reviewer.md) **(HARD FAIL tier)** — what to look for in a Daml PR. - [`idioms.md`](./idioms.md), [`gotchas.md`](./gotchas.md). -- [`../../invariants/invariance-framework.md`](../../invariants/invariance-framework.md). +- [`../../invariants/invariants-framework.md`](../../invariants/invariants-framework.md). - [`../../workflows/infrastructure-and-devops.md`](../../workflows/infrastructure-and-devops.md) — Canton infra context. - Upstream: [Canton Network Docs](https://docs.canton.network) — authoritative Daml language and Canton platform reference ([canonical source](../../references/sources.md#canton-network-docs-daml-language--canton-platform)). diff --git a/languages/daml/developer.md b/languages/daml/developer.md index 52358ef..f3de1b3 100644 --- a/languages/daml/developer.md +++ b/languages/daml/developer.md @@ -6,7 +6,7 @@ Idiomatic Daml development at ChainSafe — primarily Canton applications (Super ## Upstream canonical reference — use it, don't re-derive it -Daml language and Canton platform semantics are documented authoritatively at [docs.canton.network](https://docs.canton.network). The handbook defers here rather than restating the language — the same posture the architect pages take toward `.invariance`. Reach for these before reconstructing semantics from memory: +Daml language and Canton platform semantics are documented authoritatively at [docs.canton.network](https://docs.canton.network). The handbook defers here rather than restating the language — the same posture the architect pages take toward `.invariants`. Reach for these before reconstructing semantics from memory: | Need | Canton docs page | |---|---| diff --git a/languages/go/architect.md b/languages/go/architect.md index a451ee9..e67f3ae 100644 --- a/languages/go/architect.md +++ b/languages/go/architect.md @@ -1,14 +1,14 @@ # Go Architect -Architectural guidance for Go projects at ChainSafe. The framework for architectural invariants is `.invariance` (see the [pointer page](../../invariants/invariance-framework.md)). This page covers the Go-specific shape of decisions that sit under that framework. +Architectural guidance for Go projects at ChainSafe. The framework for architectural invariants is `.invariants` (see the [pointer page](../../invariants/invariants-framework.md)). This page covers the Go-specific shape of decisions that sit under that framework. > **In one line:** Small public surfaces. Concrete types behind interfaces only where they earn it. Errors are values; panics are programming bugs. -## Defer to `.invariance` for +## Defer to `.invariants` for -Architectural decisions in this language should be expressed in `.invariance` terms wherever they apply. Start with the upstream framework and only return here for Go-specific shaping. +Architectural decisions in this language should be expressed in `.invariants` terms wherever they apply. Start with the upstream framework and only return here for Go-specific shaping. -| If you are deciding… | Go to (`.invariance`) | +| If you are deciding… | Go to (`.invariants`) | |---|---| | What is the system boundary? | The framework's boundary-definition section | | What invariants does this service hold? | Invariant naming + testability | @@ -103,7 +103,7 @@ When opening an ADR for a Go service or significant Go module, the template shou - **Error contract.** What errors callers see. Which are sentinel, which are typed, which are wrapped. - **Resource ownership.** Connections, files, goroutines — who closes them, when. - **Dependency choices.** Any external (non-stdlib, non-`x/*`, non-project-approved) dependency the design assumes, with the compelling-case justification per the stdlib-first rule above. -- **Invariants impacted.** Deep links into `.invariance` for the architectural invariants this decision touches. +- **Invariants impacted.** Deep links into `.invariants` for the architectural invariants this decision touches. ## Anti-patterns @@ -119,4 +119,4 @@ When opening an ADR for a Go service or significant Go module, the template shou - [`developer.md`](./developer.md) — implementation-level Go practice. - [`reviewer.md`](./reviewer.md) — what to look for in a Go PR. - [`idioms.md`](./idioms.md) and [`gotchas.md`](./gotchas.md) — shared shorter references. -- [`../../invariants/invariance-framework.md`](../../invariants/invariance-framework.md) — the architectural framework this page defers to. +- [`../../invariants/invariants-framework.md`](../../invariants/invariants-framework.md) — the architectural framework this page defers to. diff --git a/languages/python/architect.md b/languages/python/architect.md index 84345b0..96296e5 100644 --- a/languages/python/architect.md +++ b/languages/python/architect.md @@ -24,9 +24,9 @@ If your task fits the second list, the language choice itself is the architectur This is [Effective Python](https://effectivepython.com/) Item 94 (*Know When and How to Replace Python with Another Programming Language*) as house policy: when a Python path turns performance-critical, profile it first (Item 92, *Profile Before Optimizing* — measure with `cProfile` / `timeit`, never guess), then push the hot part into a native extension or another language rather than micro-optimizing Python. Python stays the glue and the velocity layer. -## Defer to `.invariance` for +## Defer to `.invariants` for -Python projects generally sit downstream of the main product architecture. The `.invariance` framework applies for cross-component invariants, but most Python work doesn't introduce new architectural invariants — it operates within existing ones. +Python projects generally sit downstream of the main product architecture. The `.invariants` framework applies for cross-component invariants, but most Python work doesn't introduce new architectural invariants — it operates within existing ones. ## Python-specific architectural choices diff --git a/languages/rust/architect.md b/languages/rust/architect.md index 57f2f13..7f0c66b 100644 --- a/languages/rust/architect.md +++ b/languages/rust/architect.md @@ -1,12 +1,12 @@ # Rust Architect -Architectural guidance for Rust projects at ChainSafe — notably [Forest](https://github.com/ChainSafe/forest) (Filecoin), [Mina-rs](https://github.com/ChainSafe/mina-rs), [ChainBridge Substrate](https://github.com/ChainSafe/chainbridge-substrate), and others. The architectural framework lives in `.invariance` (see the [pointer page](../../invariants/invariance-framework.md)); this page covers Rust-specific shaping. +Architectural guidance for Rust projects at ChainSafe — notably [Forest](https://github.com/ChainSafe/forest) (Filecoin), [Mina-rs](https://github.com/ChainSafe/mina-rs), [ChainBridge Substrate](https://github.com/ChainSafe/chainbridge-substrate), and others. The architectural framework lives in `.invariants` (see the [pointer page](../../invariants/invariants-framework.md)); this page covers Rust-specific shaping. > **In one line:** Errors are typed. Ownership is explicit. Async runtime is a library choice, not a default. Use the type system instead of comments. -## Defer to `.invariance` for +## Defer to `.invariants` for -| Decision | `.invariance` section | +| Decision | `.invariants` section | |---|---| | Service boundaries and contracts | Component contracts | | Invariant naming and testability | Invariant lifecycle | @@ -81,7 +81,7 @@ When opening an ADR for a Rust crate, the template should cover: - **Error type.** Typed (`thiserror`) or pass-through (`anyhow`). Justify. - **Async commitments.** Which runtime, where the runtime is required, how the crate's API is shaped around async. - **Unsafe code.** If any `unsafe { }` is involved, justify the soundness argument and the safety invariants the caller must uphold. -- **Invariants impacted.** Deep links into `.invariance`. +- **Invariants impacted.** Deep links into `.invariants`. ## Anti-patterns @@ -99,5 +99,5 @@ When opening an ADR for a Rust crate, the template should cover: - [`reviewer.md`](./reviewer.md) — what to look for in a Rust PR. - [`idioms.md`](./idioms.md), [`gotchas.md`](./gotchas.md). - Forest's [`AI_POLICY.md`](https://github.com/ChainSafe/forest/blob/main/AI_POLICY.md) — Filecoin/Forest-specific AI norms; informs Rust review at ChainSafe. -- [`../../invariants/invariance-framework.md`](../../invariants/invariance-framework.md) — architectural framework this page defers to. +- [`../../invariants/invariants-framework.md`](../../invariants/invariants-framework.md) — architectural framework this page defers to. - [Effective Rust](https://effective-rust.com/) (Drysdale) and [The Rust Book](https://doc.rust-lang.org/book/) — the canonical practice references this section builds on; cataloged in [`sources.md`](../../references/sources.md). diff --git a/languages/solidity/architect.md b/languages/solidity/architect.md index bde0fc3..96ebdc9 100644 --- a/languages/solidity/architect.md +++ b/languages/solidity/architect.md @@ -1,12 +1,12 @@ # Solidity Architect -Architectural guidance for Solidity (and EVM-adjacent) work at ChainSafe — [Sygma](https://github.com/sygmaprotocol) and the broader crypto/bridging surface. The architectural framework is `.invariance` (see the [pointer page](../../invariants/invariance-framework.md)); this page covers Solidity-specific shaping. +Architectural guidance for Solidity (and EVM-adjacent) work at ChainSafe — [Sygma](https://github.com/sygmaprotocol) and the broader crypto/bridging surface. The architectural framework is `.invariants` (see the [pointer page](../../invariants/invariants-framework.md)); this page covers Solidity-specific shaping. > **In one line:** Every Solidity decision is a security decision. Upgrade safety, reentrancy, and audit-readiness are first-class architectural concerns. -## Defer to `.invariance` for +## Defer to `.invariants` for -| Decision | `.invariance` section | +| Decision | `.invariants` section | |---|---| | Cross-contract contracts and invariants | Component contracts | | Upgrade lifecycle invariants | Lifecycle / migration invariants | @@ -68,7 +68,7 @@ For cross-chain code: - **Failure mode for the destination chain** — what happens if delivery fails or is censored? - **Slashing / signer-set rotation** — how do signer changes propagate? -Each becomes an `.invariance` entry; reviewer skills check them per-PR. +Each becomes an `.invariants` entry; reviewer skills check them per-PR. ## ADR shape for Solidity contracts @@ -80,7 +80,7 @@ Every non-trivial Solidity ADR covers: - **Storage layout.** For upgradeable contracts, storage layout is part of the contract; ADR documents the layout and the gap pattern. - **Audit plan.** When the contract is audited (pre-deploy, post-deploy, recurring), by whom. - **Test coverage commitments.** Unit, fuzz, invariant tests, formal verification if applicable. -- **Invariants impacted.** Deep links into `.invariance`. +- **Invariants impacted.** Deep links into `.invariants`. ## Anti-patterns @@ -96,4 +96,4 @@ Every non-trivial Solidity ADR covers: - [`developer.md`](./developer.md), [`reviewer.md`](./reviewer.md) (HARD FAIL tier), [`idioms.md`](./idioms.md), [`gotchas.md`](./gotchas.md). - [`../../workflows/testing-and-qa.md`](../../workflows/testing-and-qa.md) — security-sensitive path discipline. -- [`../../invariants/invariance-framework.md`](../../invariants/invariance-framework.md). +- [`../../invariants/invariants-framework.md`](../../invariants/invariants-framework.md). diff --git a/languages/typescript/architect.md b/languages/typescript/architect.md index a205c42..d59e2fd 100644 --- a/languages/typescript/architect.md +++ b/languages/typescript/architect.md @@ -1,12 +1,12 @@ # TypeScript Architect -Architectural guidance for TypeScript projects at ChainSafe — [Lodestar](https://github.com/ChainSafe/lodestar) (Ethereum consensus client), [web3.js 4.x](https://github.com/ChainSafe/web3.js), [ssz](https://github.com/ChainSafe/ssz), [bls](https://github.com/ChainSafe/bls), [filsnap](https://github.com/ChainSafe/filsnap), and others. The architectural framework is `.invariance` (see the [pointer page](../../invariants/invariance-framework.md)). +Architectural guidance for TypeScript projects at ChainSafe — [Lodestar](https://github.com/ChainSafe/lodestar) (Ethereum consensus client), [web3.js 4.x](https://github.com/ChainSafe/web3.js), [ssz](https://github.com/ChainSafe/ssz), [bls](https://github.com/ChainSafe/bls), [filsnap](https://github.com/ChainSafe/filsnap), and others. The architectural framework is `.invariants` (see the [pointer page](../../invariants/invariants-framework.md)). > **In one line:** Strict mode, branded types for domain values, no `any`. ESM by default. Public API stability via type-level tests. -## Defer to `.invariance` for +## Defer to `.invariants` for -| Decision | `.invariance` section | +| Decision | `.invariants` section | |---|---| | Service boundaries | Component contracts | | Invariant naming + testability | Invariant lifecycle | @@ -75,7 +75,7 @@ When opening an ADR for a TS project or significant module: - **Async commitments.** Where cancellation is propagated; where parallelism is exploited. - **Error contract.** Thrown types vs. returned types. How callers should handle each. - **Build target.** Node version, browser support, ESM/CJS, bundler. -- **Invariants impacted.** Deep links into `.invariance`. +- **Invariants impacted.** Deep links into `.invariants`. ## Anti-patterns @@ -90,4 +90,4 @@ When opening an ADR for a TS project or significant module: - [`developer.md`](./developer.md) — implementation-level practice. - [`reviewer.md`](./reviewer.md), [`idioms.md`](./idioms.md), [`gotchas.md`](./gotchas.md). -- [`../../invariants/invariance-framework.md`](../../invariants/invariance-framework.md) — the architectural framework. +- [`../../invariants/invariants-framework.md`](../../invariants/invariants-framework.md) — the architectural framework. diff --git a/languages/zig/architect.md b/languages/zig/architect.md index 257ca16..c6cc1a5 100644 --- a/languages/zig/architect.md +++ b/languages/zig/architect.md @@ -1,6 +1,6 @@ # Zig Architect -Architectural guidance for Zig at ChainSafe. The canonical codebase is [lodestar-z](https://github.com/ChainSafe/lodestar-z) — Zig consensus libraries for Lodestar: SSZ serialization, Merkleization, hashing, persistent Merkle trees, and the Ethereum consensus types, consumed by the TypeScript client across a C-ABI boundary. The architectural framework lives in `.invariance` (see the [pointer page](../../invariants/invariance-framework.md)); this page covers Zig-specific shaping. +Architectural guidance for Zig at ChainSafe. The canonical codebase is [lodestar-z](https://github.com/ChainSafe/lodestar-z) — Zig consensus libraries for Lodestar: SSZ serialization, Merkleization, hashing, persistent Merkle trees, and the Ethereum consensus types, consumed by the TypeScript client across a C-ABI boundary. The architectural framework lives in `.invariants` (see the [pointer page](../../invariants/invariants-framework.md)); this page covers Zig-specific shaping. > **In one line:** Allocators are explicit and injected. Errors are values. Safety is a build-mode decision you make on purpose. Comptime replaces macros. The exported C ABI is a contract. @@ -10,9 +10,9 @@ Zig earns its place where the realistic alternative is C: small, performance-cri It is **not** the default for general work. Services and tooling have a chosen language already: TypeScript (Lodestar), Go (Gossamer), Rust (Forest), Solidity (contracts), Python (ops/scripts). Reaching for Zig outside the "C-replacement library" niche is an org-level decision, not an individual-PR one — raise it with the curator and capture the rationale in an ADR before starting. -## Defer to `.invariance` for +## Defer to `.invariants` for -| Decision | `.invariance` section | +| Decision | `.invariants` section | |---|---| | Service/module boundaries and contracts | Component contracts | | Invariant naming and testability | Invariant lifecycle | @@ -70,7 +70,7 @@ Zig is pre-1.0; the language and standard library change across releases. Pin `m - **Comptime surface.** What is resolved at compile time and why. - **Exported C ABI.** The stable surface and cross-boundary memory ownership, if any. - **Zig version floor.** The `minimum_zig_version` and the upgrade story. -- **Invariants impacted.** Deep links into `.invariance`. +- **Invariants impacted.** Deep links into `.invariants`. ## Anti-patterns @@ -85,5 +85,5 @@ Zig is pre-1.0; the language and standard library change across releases. Pin `m - [`developer.md`](./developer.md) — implementation-level Zig practice. - [`reviewer.md`](./reviewer.md) — what to look for in a Zig PR. - [`idioms.md`](./idioms.md), [`gotchas.md`](./gotchas.md). -- [`../../invariants/invariance-framework.md`](../../invariants/invariance-framework.md) — the architectural framework this page defers to. +- [`../../invariants/invariants-framework.md`](../../invariants/invariants-framework.md) — the architectural framework this page defers to. - [Zig Language Reference](https://ziglang.org/documentation/master/) and [Learn Zig](https://ziglang.org/learn/) — the upstream canonical guidance this page is built on. diff --git a/llms.txt b/llms.txt index 70986fe..c8ac052 100644 --- a/llms.txt +++ b/llms.txt @@ -18,7 +18,7 @@ URLs below point at the `main` branch and resolve to raw markdown. - [Engineering Invariants](https://raw.githubusercontent.com/ChainSafe/engineering-handbook/main/invariants/engineering-invariants.md): The seven non-negotiables (open-source by default, standards enforced, quality defined before build, composable by design, decisions in the repo, ship value not effort, auditable context). - [Agent-Era Invariants](https://raw.githubusercontent.com/ChainSafe/engineering-handbook/main/invariants/agent-era-invariants.md): Eight invariants specific to agent-assisted work (no silent edits, no fabrication, no secret commits, no protected-branch push, scope boundary, no external comms without per-message auth, no HARD FAIL bypass, audit trail). -- [.invariance Framework (pointer)](https://raw.githubusercontent.com/ChainSafe/engineering-handbook/main/invariants/invariance-framework.md): Deep-link map into Martin Maurer's `.invariance` repo for architectural invariants. Maintained by [@boorich](https://github.com/boorich). +- [.invariants Framework (pointer)](https://raw.githubusercontent.com/ChainSafe/engineering-handbook/main/invariants/invariants-framework.md): Deep-link map into [@boorich/.invariants-starter-kit](https://github.com/boorich/.invariants-starter-kit) and [landing page](https://boorich.github.io/.invariants-starter-kit/). Maintained by [@boorich](https://github.com/boorich). ## Workflows @@ -36,7 +36,7 @@ URLs below point at the `main` branch and resolve to raw markdown. ### Go (Gossamer) -- [Go Architect](https://raw.githubusercontent.com/ChainSafe/engineering-handbook/main/languages/go/architect.md): Project layout, public surface discipline, concurrency model, error model. Defers to `.invariance`. +- [Go Architect](https://raw.githubusercontent.com/ChainSafe/engineering-handbook/main/languages/go/architect.md): Project layout, public surface discipline, concurrency model, error model. Defers to `.invariants`. - [Go Developer](https://raw.githubusercontent.com/ChainSafe/engineering-handbook/main/languages/go/developer.md): golangci-lint, gomock conventions, argument-passing heuristics, panic discipline, context propagation, CI baseline. - [Go Reviewer (SOFT WARNING tier)](https://raw.githubusercontent.com/ChainSafe/engineering-handbook/main/languages/go/reviewer.md): Checklist for reviewing Go PRs. Concurrency, errors, panic, layout, testing. - [Go Idioms](https://raw.githubusercontent.com/ChainSafe/engineering-handbook/main/languages/go/idioms.md) · [Go Gotchas](https://raw.githubusercontent.com/ChainSafe/engineering-handbook/main/languages/go/gotchas.md) @@ -79,7 +79,7 @@ URLs below point at the `main` branch and resolve to raw markdown. ### Zig (lodestar-z) -- [Zig Architect](https://raw.githubusercontent.com/ChainSafe/engineering-handbook/main/languages/zig/architect.md): When to reach for Zig, project layout (build.zig / build.zig.zon, modules), allocator strategy, error model, build-mode / safety posture, comptime, the C-ABI contract. Defers to `.invariance`. +- [Zig Architect](https://raw.githubusercontent.com/ChainSafe/engineering-handbook/main/languages/zig/architect.md): When to reach for Zig, project layout (build.zig / build.zig.zon, modules), allocator strategy, error model, build-mode / safety posture, comptime, the C-ABI contract. Defers to `.invariants`. - [Zig Developer](https://raw.githubusercontent.com/ChainSafe/engineering-handbook/main/languages/zig/developer.md): `zig fmt`, the build system, version pinning, allocator / `defer` / `errdefer` discipline, error unions, integer-overflow and safety, comptime, testing (`std.testing.allocator`, spec tests, fuzzing), C interop, CI baseline. - [Zig Reviewer (SOFT WARNING; memory-safety + consensus near-HARD-FAIL)](https://raw.githubusercontent.com/ChainSafe/engineering-handbook/main/languages/zig/reviewer.md): Checklist for Zig PRs. Allocator / leak discipline, swallowed errors, undefined behavior, pointer-cast soundness, consensus correctness. Override mechanics logged in PR. - [Zig Idioms](https://raw.githubusercontent.com/ChainSafe/engineering-handbook/main/languages/zig/idioms.md) · [Zig Gotchas](https://raw.githubusercontent.com/ChainSafe/engineering-handbook/main/languages/zig/gotchas.md) @@ -116,7 +116,7 @@ Packaged Anthropic Skills authored via `skill-creator`. Each skill is self-conta The handbook deep-links into these upstream sources rather than duplicating them. See [`references/sources.md`](https://raw.githubusercontent.com/ChainSafe/engineering-handbook/main/references/sources.md) for the full catalog with maintainer and coordination notes. -- [.invariance framework](https://github.com/boorich): Martin Maurer's architectural invariance project. Canonical source for architecture and system-design invariants. +- [.invariants starter kit](https://github.com/boorich/.invariants-starter-kit): Dotfile convention + reference workspace. [Landing page](https://boorich.github.io/.invariants-starter-kit/). Canonical source for architecture and system-design invariants. - [ChainSafe/infrastructure-general](https://github.com/ChainSafe/infrastructure-general): Canonical source for infrastructure, IaC, deployment, observability, on-call, runbooks. Maintained by [@joshdougall](https://github.com/joshdougall). Ships its own [AGENTS.md](https://github.com/ChainSafe/infrastructure-general/blob/main/AGENTS.md) and [CLAUDE.md](https://github.com/ChainSafe/infrastructure-general/blob/main/CLAUDE.md). - [ChainSafe/forest — AI_POLICY.md](https://github.com/ChainSafe/forest/blob/main/AI_POLICY.md): AI-assisted-development policy for the Filecoin client. Originally adapted from the [Ghostty project](https://github.com/ghostty-org/ghostty); attribution preserved. Carried through into the handbook's testing-and-qa and Rust reviewer pages. - [Anthropic Skills Specification](https://github.com/anthropics/skills): The canonical playbook for skill authoring. Every skill in this repo is authored via `anthropic-skills:skill-creator`. diff --git a/operating-model/collaborator-statement.md b/operating-model/collaborator-statement.md index bbe3054..bd282d3 100644 --- a/operating-model/collaborator-statement.md +++ b/operating-model/collaborator-statement.md @@ -63,7 +63,7 @@ The agent stops and asks — without refusing — when: - The operator's intent is ambiguous and the choices have meaningfully different consequences. - A section this handbook claims to have does not exist yet. - An operator instruction conflicts with a documented invariant or convention. -- An external canonical source (`.invariance`, `infrastructure-general`) does not have a target the handbook expects to be there. +- An external canonical source (`.invariants`, `infrastructure-general`) does not have a target the handbook expects to be there. Escalation is not failure. It is the agent doing its job. diff --git a/operating-model/mcp-and-llm-txt.md b/operating-model/mcp-and-llm-txt.md index 55cc7f3..91b77b8 100644 --- a/operating-model/mcp-and-llm-txt.md +++ b/operating-model/mcp-and-llm-txt.md @@ -41,7 +41,7 @@ URLs in the live file point at the **raw markdown content** on GitHub (or `chain - **Project identity.** Title, one-line description, link to the human README. - **Section deep links.** One entry per handbook section (`operating-model/collaborator-statement.md`, `invariants/engineering-invariants.md`, `workflows/pr-authoring.md`, etc.) — keyed by question or intent, not by file structure. - **Skill listings.** Every packaged skill in [`skills/`](../skills/) gets an entry: name, one-line description (matching the SKILL.md frontmatter), direct URL to the raw `SKILL.md`, and trigger conditions so foreign agents can decide whether to load it. -- **External canonical sources.** Deep links into the upstream `.invariance` and `ChainSafe/infrastructure-general` repos where the handbook defers to them. +- **External canonical sources.** Deep links into the upstream `.invariants` and `ChainSafe/infrastructure-general` repos where the handbook defers to them. ### What does not go in it @@ -69,7 +69,7 @@ This is the agent-facing index. For humans, see the - [chainsafe-research-plan-implement](https://raw.githubusercontent.com/ChainSafe/engineering-handbook/main/skills/chainsafe-research-plan-implement/SKILL.md): Research → plan → annotate → implement workflow. Trigger: any multi-file change, refactor, new feature. ## External canonical sources -- [.invariance framework](https://github.com/.../README.md): Architecture invariance framework. The handbook's `languages//architect.md` pages deep-link here. +- [.invariants starter kit](https://github.com/boorich/.invariants-starter-kit): `.invariants` framework. The handbook's `languages//architect.md` pages deep-link here. - [ChainSafe/infrastructure-general](https://github.com/ChainSafe/infrastructure-general/blob/main/AGENTS.md): Infrastructure & DevOps canonical source. The handbook's `workflows/infrastructure-and-devops.md` deep-links here. ``` @@ -106,7 +106,7 @@ CI guarantees `llms.txt` does not drift from the handbook content: - Every skill in [`skills/`](../skills/) must appear in `llms.txt`. - Every `llms.txt` skill entry must resolve to an existing `SKILL.md`. -- All external deep links (into `.invariance`, `infrastructure-general`, Forest, etc.) are link-checked in CI and the build fails on any broken target. +- All external deep links (into `.invariants`, `infrastructure-general`, Forest, etc.) are link-checked in CI and the build fails on any broken target. When you add a new skill, section, or pointer page: update `llms.txt` in the same PR. The handbook treats the index and the content as a single commit, not two. diff --git a/operating-model/model-and-tool-selection.md b/operating-model/model-and-tool-selection.md index 792d9c6..6f28fe6 100644 --- a/operating-model/model-and-tool-selection.md +++ b/operating-model/model-and-tool-selection.md @@ -67,7 +67,7 @@ That is the default. Everything else is on-demand. - **GitHub MCP** — when opening PRs, reading issues, listing branches, working with reviews. - **`ChainSafe/infrastructure-general`** — when touching infra, IaC, observability, deploys, runbooks. Coordinate with `@joshdougall` as the canonical owner. -- **`.invariance` repo** — when doing architecture or system-design work. Coordinate with `@boorich` as the framework maintainer. +- **[`.invariants` starter kit](https://github.com/boorich/.invariants-starter-kit)** — when doing architecture or system-design work. Coordinate with `@boorich` as the framework maintainer. - **Linear / Jira / project-tracker MCPs** — when the task involves issue triage, sprint planning, or status updates. - **Slack / Discord / email MCPs** — when the task involves communication. Note the [external-communication gate](./gates-and-escalation.md#4-external-communication). - **Product-specific repos** (`ChainSafe/forest`, `ChainSafe/lodestar`, `ChainSafe/sygma`, etc.) — when working on that product. Do not load a product repo just to browse it; the operator authorized work on a specific scope. diff --git a/references/sources.md b/references/sources.md index aad46c9..4ef646a 100644 --- a/references/sources.md +++ b/references/sources.md @@ -18,12 +18,12 @@ Entries are added when the handbook starts deferring to a new source. Removal is ## Sources -### `.invariance` framework +### `.invariants` framework -- **Source.** Martin Maurer's `.invariance` repo. See [`../invariants/invariance-framework.md`](../invariants/invariance-framework.md) for the deep-link map. +- **Source.** [github.com/boorich/.invariants-starter-kit](https://github.com/boorich/.invariants-starter-kit) (convention + optional reference workspace). Landing page: [boorich.github.io/.invariants-starter-kit/](https://boorich.github.io/.invariants-starter-kit/). Deep-link map: [`../invariants/invariants-framework.md`](../invariants/invariants-framework.md). - **Maintainer.** [@boorich](https://github.com/boorich) (Martin Maurer). -- **Covers.** Architectural invariants — what they are, how they are named, how they are tested, how they are versioned, how violations are reported. Multi-repo convention. -- **Used by.** [`../invariants/invariance-framework.md`](../invariants/invariance-framework.md) (pointer page); every [`../languages//architect.md`](../languages/) page deep-links into per-language invariant sections; ADR templates referenced from [`../workflows/pr-authoring.md`](../workflows/) require an "Invariants impacted" field sourced from `.invariance`. +- **Covers.** Architectural invariants — dotfile format, severity cascade, conformance agent, optional vecs code index and GitHub triage. Multi-repo convention. +- **Used by.** [`../invariants/invariants-framework.md`](../invariants/invariants-framework.md) (pointer page); every [`../languages//architect.md`](../languages/) page deep-links into per-language invariant sections; ADR templates referenced from [`../workflows/pr-authoring.md`](../workflows/) require an "Invariants impacted" field sourced from `.invariants`. - **Coordination.** [@boorich](https://github.com/boorich) is CODEOWNER for the pointer page. Anchor changes upstream → re-anchor here in the same PR (or close behind). ### `ChainSafe/infrastructure-general` @@ -62,7 +62,7 @@ Entries are added when the handbook starts deferring to a new source. Removal is - **Source.** [docs.canton.network](https://docs.canton.network) — the official Canton Network documentation: the Daml language, the app-development modules, deep dives, tooling, and the full Daml standard-library reference. Machine-readable index at [`docs.canton.network/llms.txt`](https://docs.canton.network/llms.txt) (every page is also served as raw markdown by appending `.md`). Upstream docs repo: [canton-network/cf-docs](https://github.com/canton-network/cf-docs). Documentation licensed CC-BY-4.0. - **Maintainer.** External — the Canton Foundation. Internal coordination via the Daml CODEOWNERS — [@boorich](https://github.com/boorich), [@salindne](https://github.com/salindne), [@sqhell](https://github.com/sqhell) — per [`.github/CODEOWNERS`](../.github/CODEOWNERS). -- **Covers.** The authoritative Daml language and Canton platform reference: authorization model, contract templates, choices, keys, interfaces, the standard library, testing with Daml Script, Smart Contract Upgrades (SCU) and upgrade compatibility, working with time, security best practices, CI/CD integration, and Canton-specific topology (domain / synchronizer / sequencer / mediator). The handbook's Daml pages defer here rather than re-deriving language semantics — the same way the architect pages defer to `.invariance`. +- **Covers.** The authoritative Daml language and Canton platform reference: authorization model, contract templates, choices, keys, interfaces, the standard library, testing with Daml Script, Smart Contract Upgrades (SCU) and upgrade compatibility, working with time, security best practices, CI/CD integration, and Canton-specific topology (domain / synchronizer / sequencer / mediator). The handbook's Daml pages defer here rather than re-deriving language semantics — the same way the architect pages defer to `.invariants`. - **Used by.** [`../languages/daml/architect.md`](../languages/daml/architect.md) (authorization / upgrade / privacy semantics), [`../languages/daml/developer.md`](../languages/daml/developer.md) (dev environment, tooling, standard library, testing), [`../languages/daml/idioms.md`](../languages/daml/idioms.md), [`../languages/daml/gotchas.md`](../languages/daml/gotchas.md), [`../languages/daml/reviewer.md`](../languages/daml/reviewer.md) (authorization, upgrade compatibility, security checks). - **Coordination.** External upstream, treated as canonical for Daml language semantics. When Canton restructures the docs, re-anchor the deep links in the same pass — the weekly link-check run catches rot. The internal deferral is reviewed by the Daml CODEOWNERS. @@ -78,7 +78,7 @@ Entries are added when the handbook starts deferring to a new source. Removal is - **Source.** [ziglang.org](https://ziglang.org) — the official Zig documentation: the [Language Reference](https://ziglang.org/documentation/master/), the [Standard Library reference](https://ziglang.org/documentation/master/std/), and the [Learn](https://ziglang.org/learn/) section (in-depth overview, the [build-system guide](https://ziglang.org/learn/build-system/), code samples, and the Style Guide). Documentation under the Zig project's MIT license. Zig is pre-1.0: the `master` docs track the unreleased compiler, and each release carries its own versioned reference. - **Maintainer.** External — the Zig Software Foundation. Internal coordination point: the Zig CODEOWNER ([@wemeetagain](https://github.com/wemeetagain) / [@matthewkeil](https://github.com/matthewkeil) / [@kalambet](https://github.com/kalambet)). -- **Covers.** The authoritative Zig language and standard-library reference: syntax, build modes and Illegal Behavior, the allocator model, error unions and `errdefer`, optionals, comptime and generics, the build system (`build.zig` / `build.zig.zon`), C interop, and the naming Style Guide. The handbook's Zig pages defer here for language semantics rather than re-deriving them — the same way the architect pages defer to `.invariance` and the Daml pages defer to the Canton docs. +- **Covers.** The authoritative Zig language and standard-library reference: syntax, build modes and Illegal Behavior, the allocator model, error unions and `errdefer`, optionals, comptime and generics, the build system (`build.zig` / `build.zig.zon`), C interop, and the naming Style Guide. The handbook's Zig pages defer here for language semantics rather than re-deriving them — the same way the architect pages defer to `.invariants` and the Daml pages defer to the Canton docs. - **Used by.** [`../languages/zig/architect.md`](../languages/zig/architect.md), [`../languages/zig/developer.md`](../languages/zig/developer.md), [`../languages/zig/reviewer.md`](../languages/zig/reviewer.md), [`../languages/zig/idioms.md`](../languages/zig/idioms.md), [`../languages/zig/gotchas.md`](../languages/zig/gotchas.md). ChainSafe's canonical Zig codebase is [lodestar-z](https://github.com/ChainSafe/lodestar-z) (consensus libraries for Lodestar). - **Coordination.** External upstream, treated as canonical for Zig language semantics. Because Zig is pre-1.0, the language and std reshape across releases — re-anchor deep links and version-pinned guidance when bumping the project's Zig version; the weekly link-check run catches rot. @@ -110,5 +110,5 @@ Surfacing known candidates rather than fabricating coverage: - [`../NOTICE`](../NOTICE) — third-party attribution required under Apache 2.0 §4(d). Sources with upstream licenses or attribution requirements are also recorded there. - [`./attribution.md`](./attribution.md) — the curatorial credit policy; how original authors are surfaced across the three-layer attribution model. - [`./CONTRIBUTORS.md`](./CONTRIBUTORS.md) — the contributor index. Maintainers named here also appear there. -- [`../invariants/invariance-framework.md`](../invariants/invariance-framework.md) — the architecture/system-design deferral that grounded this catalog. +- [`../invariants/invariants-framework.md`](../invariants/invariants-framework.md) — the architecture/system-design deferral that grounded this catalog. - [`../workflows/infrastructure-and-devops.md`](../workflows/infrastructure-and-devops.md) — the infrastructure deferral that grounded this catalog. diff --git a/skills/chainsafe-go-architect/SKILL.md b/skills/chainsafe-go-architect/SKILL.md index 968a30c..3298fcb 100644 --- a/skills/chainsafe-go-architect/SKILL.md +++ b/skills/chainsafe-go-architect/SKILL.md @@ -1,6 +1,6 @@ --- name: chainsafe-go-architect -description: Architectural guidance for designing Go services and systems at ChainSafe (Gossamer and Go projects). Use whenever the user starts a new Go service, designs a Go module, writes an ADR for Go work, picks concurrency patterns, decides on a public API surface, structures a Go workspace, or makes any Go-specific architectural decision. EVEN IF the user does not explicitly say "architecture" — triggers on "design a Go service", "new Go module", "Go project layout", "concurrency model in Go", "public API for this Go package", "ADR for Go", "internal vs pkg", "channels or mutexes", "interface design in Go", "context propagation", "goroutine ownership". Defers to `.invariance` for invariants. Do NOT use for line-level Go coding (use chainsafe-go-developer) or Go PR review (use chainsafe-go-reviewer). +description: Architectural guidance for designing Go services and systems at ChainSafe (Gossamer and Go projects). Use whenever the user starts a new Go service, designs a Go module, writes an ADR for Go work, picks concurrency patterns, decides on a public API surface, structures a Go workspace, or makes any Go-specific architectural decision. EVEN IF the user does not explicitly say "architecture" — triggers on "design a Go service", "new Go module", "Go project layout", "concurrency model in Go", "public API for this Go package", "ADR for Go", "internal vs pkg", "channels or mutexes", "interface design in Go", "context propagation", "goroutine ownership". Defers to `.invariants` for invariants. Do NOT use for line-level Go coding (use chainsafe-go-developer) or Go PR review (use chainsafe-go-reviewer). metadata: type: role-workflow language: go @@ -15,7 +15,7 @@ Use this when designing Go systems at ChainSafe — Gossamer-shaped work or any ## Operating context -You are the architect role for Go work. The architectural framework (invariant naming, lifecycle, testability) is `.invariance`; consult [`invariants/invariance-framework.md`](../../invariants/invariance-framework.md) and the upstream `.invariance` repo before proposing a design. This skill covers what is Go-specific *under* that framework. +You are the architect role for Go work. The architectural framework (invariant naming, lifecycle, testability) is `.invariants`; consult [`invariants/invariants-framework.md`](../../invariants/invariants-framework.md) and [boorich/.invariants-starter-kit](https://github.com/boorich/.invariants-starter-kit) before proposing a design. This skill covers what is Go-specific *under* that framework. The full reference is [`languages/go/architect.md`](../../languages/go/architect.md). Load that file for the complete guidance. @@ -41,9 +41,9 @@ Every non-trivial Go ADR should cover: - Concurrency commitments: goroutine ownership, context propagation, cancellation. - Error contract: which errors callers see, sentinel vs typed vs wrapped. - Resource ownership: connections, files, goroutines — who closes them, when. -- Invariants impacted: deep links into `.invariance`. +- Invariants impacted: deep links into `.invariants`. -## Defer to `.invariance` for +## Defer to `.invariants` for - The invariant definitions and lifecycle. - Cross-service contracts. @@ -64,4 +64,4 @@ This skill covers Go-specific *shape*; the framework is upstream. - Full reference: [`languages/go/architect.md`](../../languages/go/architect.md) - Sister roles: `chainsafe-go-developer` (implementation), `chainsafe-go-reviewer` (PR review) - Workflow: `chainsafe-research-plan-implement` for the design-to-implementation flow -- Framework: [`invariants/invariance-framework.md`](../../invariants/invariance-framework.md) +- Framework: [`invariants/invariants-framework.md`](../../invariants/invariants-framework.md) diff --git a/skills/chainsafe-rust-architect/SKILL.md b/skills/chainsafe-rust-architect/SKILL.md index dd5e81b..f60ff7c 100644 --- a/skills/chainsafe-rust-architect/SKILL.md +++ b/skills/chainsafe-rust-architect/SKILL.md @@ -1,6 +1,6 @@ --- name: chainsafe-rust-architect -description: Architectural guidance for designing Rust crates and systems at ChainSafe (Forest, Mina-rs, ChainBridge Substrate, PINT, other Rust projects). Use this skill whenever the user is starting a new Rust crate, designing a Rust workspace, choosing an async runtime, picking an error model, deciding `unsafe` usage, structuring a Cargo workspace, deciding `pub` vs `pub(crate)`, picking concurrency primitives, or writing an ADR for Rust work. EVEN IF the user does not explicitly say "architecture" — triggers on "design a Rust crate", "new Rust workspace", "Forest module design", "thiserror or anyhow", "async runtime choice", "Tokio vs async-std", "Arc> or channel", "public API surface", "is unsafe justified here", "ADR for Rust", "non_exhaustive enum", "workspace layout". Defers to .invariance for invariants themselves; covers what Rust changes about applying them. Do NOT use for line-level Rust coding (use chainsafe-rust-developer) or Rust PR review (use chainsafe-rust-reviewer). +description: Architectural guidance for designing Rust crates and systems at ChainSafe (Forest, Mina-rs, ChainBridge Substrate, PINT, other Rust projects). Use this skill whenever the user is starting a new Rust crate, designing a Rust workspace, choosing an async runtime, picking an error model, deciding `unsafe` usage, structuring a Cargo workspace, deciding `pub` vs `pub(crate)`, picking concurrency primitives, or writing an ADR for Rust work. EVEN IF the user does not explicitly say "architecture" — triggers on "design a Rust crate", "new Rust workspace", "Forest module design", "thiserror or anyhow", "async runtime choice", "Tokio vs async-std", "Arc> or channel", "public API surface", "is unsafe justified here", "ADR for Rust", "non_exhaustive enum", "workspace layout". Defers to .invariants for invariants themselves; covers what Rust changes about applying them. Do NOT use for line-level Rust coding (use chainsafe-rust-developer) or Rust PR review (use chainsafe-rust-reviewer). metadata: type: role-workflow language: rust @@ -64,7 +64,7 @@ ChainSafe Rust projects use Cargo workspaces (Forest is the canonical example): - Error type — `thiserror` or `anyhow`. Justify. - Async commitments — which runtime, where required, how the API is shaped. - Unsafe — if any, the soundness argument and safety invariants. -- Invariants impacted — deep links into `.invariance`. +- Invariants impacted — deep links into `.invariants`. ## Anti-patterns at design time @@ -82,6 +82,6 @@ Forest carries [`AI_POLICY.md`](https://github.com/ChainSafe/forest/blob/main/AI - Full reference: [`languages/rust/architect.md`](../../languages/rust/architect.md) - Sister roles: `chainsafe-rust-developer`, `chainsafe-rust-reviewer` -- Framework: [`invariants/invariance-framework.md`](../../invariants/invariance-framework.md) +- Framework: [`invariants/invariants-framework.md`](../../invariants/invariants-framework.md) - Workflow: `chainsafe-research-plan-implement` - Upstream: [Effective Rust](https://effective-rust.com/) · [The Rust Book](https://doc.rust-lang.org/book/) diff --git a/skills/chainsafe-solidity-architect/SKILL.md b/skills/chainsafe-solidity-architect/SKILL.md index c2c6373..1807031 100644 --- a/skills/chainsafe-solidity-architect/SKILL.md +++ b/skills/chainsafe-solidity-architect/SKILL.md @@ -65,7 +65,7 @@ Migrating between upgrade strategies is itself a migration risk. Pick once. - Storage layout — slot map for upgradeable; gap pattern. - Audit plan — when, by whom, recurring vs pre-deploy. - Test coverage commitments — unit, fuzz, invariant, formal verification. -- Invariants impacted — deep links into `.invariance`. +- Invariants impacted — deep links into `.invariants`. ## Anti-patterns at design time diff --git a/skills/chainsafe-typescript-architect/SKILL.md b/skills/chainsafe-typescript-architect/SKILL.md index c40cda2..e089111 100644 --- a/skills/chainsafe-typescript-architect/SKILL.md +++ b/skills/chainsafe-typescript-architect/SKILL.md @@ -1,6 +1,6 @@ --- name: chainsafe-typescript-architect -description: Architectural guidance for designing TypeScript projects at ChainSafe (Lodestar, web3.js 4.x, ssz, bls, filsnap, other TS projects). Use this skill whenever the user is starting a new TypeScript project, designing a TS package, structuring a Yarn 3 monorepo workspace, picking ESM vs CJS, deciding on type strictness baseline, designing public APIs with branded types, choosing testing frameworks, or writing an ADR for TS work. EVEN IF the user does not explicitly say "architecture" — triggers on "design a TS package", "new TS project", "Lodestar architecture", "monorepo setup", "Yarn workspaces", "ESM or CJS", "branded types", "public API design", "ADR for TypeScript", "tsconfig strict baseline", "type-level tests". Defers to .invariance for invariants themselves. Do NOT use for line-level TS coding (use chainsafe-typescript-developer) or TS PR review (use chainsafe-typescript-reviewer). +description: Architectural guidance for designing TypeScript projects at ChainSafe (Lodestar, web3.js 4.x, ssz, bls, filsnap, other TS projects). Use this skill whenever the user is starting a new TypeScript project, designing a TS package, structuring a Yarn 3 monorepo workspace, picking ESM vs CJS, deciding on type strictness baseline, designing public APIs with branded types, choosing testing frameworks, or writing an ADR for TS work. EVEN IF the user does not explicitly say "architecture" — triggers on "design a TS package", "new TS project", "Lodestar architecture", "monorepo setup", "Yarn workspaces", "ESM or CJS", "branded types", "public API design", "ADR for TypeScript", "tsconfig strict baseline", "type-level tests". Defers to .invariants for invariants themselves. Do NOT use for line-level TS coding (use chainsafe-typescript-developer) or TS PR review (use chainsafe-typescript-reviewer). metadata: type: role-workflow language: typescript @@ -72,7 +72,7 @@ Domain identifiers must not be interchangeable. Branded types enforce at the typ - Async commitments — where cancellation propagates; where parallelism is exploited. - Error contract — thrown types vs returned types. - Build target — Node version, browser support, ESM/CJS, bundler. -- Invariants impacted — deep links into `.invariance`. +- Invariants impacted — deep links into `.invariants`. ## Anti-patterns at design time @@ -87,5 +87,5 @@ Domain identifiers must not be interchangeable. Branded types enforce at the typ - Full reference: [`languages/typescript/architect.md`](../../languages/typescript/architect.md) - Sister roles: `chainsafe-typescript-developer`, `chainsafe-typescript-reviewer` -- Framework: [`invariants/invariance-framework.md`](../../invariants/invariance-framework.md) +- Framework: [`invariants/invariants-framework.md`](../../invariants/invariants-framework.md) - Workflow: `chainsafe-research-plan-implement` diff --git a/skills/chainsafe-zig-architect/SKILL.md b/skills/chainsafe-zig-architect/SKILL.md index f02d9f0..c41ddaa 100644 --- a/skills/chainsafe-zig-architect/SKILL.md +++ b/skills/chainsafe-zig-architect/SKILL.md @@ -1,6 +1,6 @@ --- name: chainsafe-zig-architect -description: Architectural guidance for designing Zig modules and libraries at ChainSafe (lodestar-z — Zig consensus libraries for Lodestar: SSZ, Merkleization, hashing, persistent Merkle trees, consensus types). Use this skill whenever the user is starting a new Zig module, designing a build.zig layout, deciding allocator ownership or strategy, choosing a build mode (ReleaseSafe vs ReleaseFast) and safety posture, designing an error set, shaping a comptime/generic API, designing a C-ABI/FFI surface for bindings, pinning a Zig version, or writing an ADR for Zig work. EVEN IF the user does not explicitly say "architecture" — triggers on "design a Zig module", "new Zig library", "build.zig layout", "allocator strategy", "arena vs gpa", "who owns this allocation", "ReleaseSafe or ReleaseFast", "Zig error set", "comptime generic", "export to C ABI", "lodestar-z module", "SSZ type design", "ADR for Zig", "minimum_zig_version". Defers to .invariance for invariants themselves; covers what Zig changes about applying them. Do NOT use for line-level Zig coding (use chainsafe-zig-developer) or Zig PR review (use chainsafe-zig-reviewer). +description: Architectural guidance for designing Zig modules and libraries at ChainSafe (lodestar-z — Zig consensus libraries for Lodestar: SSZ, Merkleization, hashing, persistent Merkle trees, consensus types). Use this skill whenever the user is starting a new Zig module, designing a build.zig layout, deciding allocator ownership or strategy, choosing a build mode (ReleaseSafe vs ReleaseFast) and safety posture, designing an error set, shaping a comptime/generic API, designing a C-ABI/FFI surface for bindings, pinning a Zig version, or writing an ADR for Zig work. EVEN IF the user does not explicitly say "architecture" — triggers on "design a Zig module", "new Zig library", "build.zig layout", "allocator strategy", "arena vs gpa", "who owns this allocation", "ReleaseSafe or ReleaseFast", "Zig error set", "comptime generic", "export to C ABI", "lodestar-z module", "SSZ type design", "ADR for Zig", "minimum_zig_version". Defers to .invariants for invariants themselves; covers what Zig changes about applying them. Do NOT use for line-level Zig coding (use chainsafe-zig-developer) or Zig PR review (use chainsafe-zig-reviewer). metadata: type: role-workflow language: zig @@ -56,7 +56,7 @@ Zig is pre-1.0; pin `minimum_zig_version` and the CI compiler, wrap heavily-used ## ADR shape for Zig modules -Allocator ownership · error set · build-mode/safety posture · comptime surface · exported C ABI + memory ownership · Zig version floor · invariants impacted (`.invariance`). +Allocator ownership · error set · build-mode/safety posture · comptime surface · exported C ABI + memory ownership · Zig version floor · invariants impacted (`.invariants`). ## Anti-patterns at design time @@ -70,6 +70,6 @@ Allocator ownership · error set · build-mode/safety posture · comptime surfac - Full reference: [`languages/zig/architect.md`](../../languages/zig/architect.md) - Sister roles: `chainsafe-zig-developer`, `chainsafe-zig-reviewer` -- Framework: [`invariants/invariance-framework.md`](../../invariants/invariance-framework.md) +- Framework: [`invariants/invariants-framework.md`](../../invariants/invariants-framework.md) - Workflow: `chainsafe-research-plan-implement` - Upstream: [Zig Language Reference](https://ziglang.org/documentation/master/), [Learn Zig](https://ziglang.org/learn/) diff --git a/workflows/repo-and-ci-setup.md b/workflows/repo-and-ci-setup.md index 84a30c7..d2af735 100644 --- a/workflows/repo-and-ci-setup.md +++ b/workflows/repo-and-ci-setup.md @@ -69,7 +69,7 @@ Disable merge commits and rebase by default; squash keeps `main` history clean. - **Create `.github/CODEOWNERS`** with the structure: - Catch-all owner at the top (a team or set of individuals). - Section-specific overrides below, ordered from general to specific. -- **For the handbook repo specifically,** the v2 model uses [@kalambet](https://github.com/kalambet) as the catch-all curator with overrides for `invariants/invariance-framework.md` (@boorich), `workflows/*` infra pointer pages (@joshdougall), etc. See [`../.github/CODEOWNERS`](../.github/CODEOWNERS). +- **For the handbook repo specifically,** the v2 model uses [@kalambet](https://github.com/kalambet) as the catch-all curator with overrides for `invariants/invariants-framework.md` (@boorich), `workflows/*` infra pointer pages (@joshdougall), etc. See [`../.github/CODEOWNERS`](../.github/CODEOWNERS). - **Verify by opening a test PR** touching the catch-all area and confirming the right reviewer is auto-requested. - **Rollback.** Revert the `.github/CODEOWNERS` file via PR. From eeaf7052154090bbc25d1414d4cfd04962e106a7 Mon Sep 17 00:00:00 2001 From: empea-careercriminal Date: Thu, 4 Jun 2026 17:13:15 +0200 Subject: [PATCH 2/5] Restore Peter's pointer-page structure. Keep deep-link map shape, inline-rules placeholder, and anchor-TBD rows; add only plural naming and starter kit URLs. --- invariants/invariants-framework.md | 66 +++++++++++++++--------------- 1 file changed, 34 insertions(+), 32 deletions(-) diff --git a/invariants/invariants-framework.md b/invariants/invariants-framework.md index 1528728..462eda1 100644 --- a/invariants/invariants-framework.md +++ b/invariants/invariants-framework.md @@ -1,69 +1,71 @@ # The `.invariants` Framework -For architecture and system-design invariants, this handbook does not re-derive a methodology. The canonical source is Martin Maurer's **`.invariants`** convention and optional reference workspace. This page's job is to deep-link into it by intent, not to duplicate it here. +For architecture and system-design invariants, this handbook does not re-derive a methodology. The canonical source is Martin Maurer's **`.invariants`** convention and optional [reference workspace](https://github.com/boorich/.invariants-starter-kit). This page's job is to deep-link into it by intent, not to gesture at it as a separate resource to "go read." | Resource | URL | |----------|-----| | **Starter kit (repo)** | [github.com/boorich/.invariants-starter-kit](https://github.com/boorich/.invariants-starter-kit) | | **Landing page** | [boorich.github.io/.invariants-starter-kit/](https://boorich.github.io/.invariants-starter-kit/) | -| **[vecs](https://github.com/boorich/vecs)** (code index CLI) | Used by the starter kit; optional for Level 1 dotfile-only adoption | -> **In one line:** Architectural invariants live in **`.invariants`** dotfiles (plural). This page is the navigation surface; the convention, examples, and agent loop live in the starter kit. +> **In one line:** Architecture invariants live in `.invariants` (plural). This page is the navigation surface; the rules themselves live upstream. -> **Filename:** **`.invariants`** — not `.invariance`. The dotfile is YAML; there is no special file terminator. +> **Filename:** **`.invariants`** — not the deprecated singular `.invariance`. The dotfile is YAML; no special file terminator. ## Why we defer here -**`.invariants`** is a multi-repo dotfile convention ([@boorich](https://github.com/boorich)). It is one of the strongest existing artifacts within ChainSafe for the question "how do we make architectural decisions consistent across products?" The handbook treats the starter kit as canonical for that question — duplicating its content here would create drift; the handbook's value here is *navigation*, not substance. +`.invariants` is a multi-repo invariant convention authored by [@boorich](https://github.com/boorich). It is one of the strongest existing artifacts within ChainSafe for the question "how do we make architectural decisions consistent across products?" The handbook treats the [starter kit](https://github.com/boorich/.invariants-starter-kit) as canonical for that question — duplicating its content here would create drift; the handbook's value here is in the *navigation*, not the substance. -## Adoption depth - -| Level | What you do | Starter kit required? | -|-------|-------------|------------------------| -| **1** | `cp .invariants.example .invariants` in your repo | No | -| **2** | Apex + per-repo cascade (`inherits`, `cascades_to`) | No | -| **3** | `bash setup.sh` — vecs code index, `gh` triage, conformance agent | Yes — [repo](https://github.com/boorich/.invariants-starter-kit) | +The deep-link map below is keyed by the question an agent or operator is trying to answer, so readers land on the exact upstream section they need. ## Deep-link map -Keyed by the question an agent or operator is trying to answer. Fetch upstream content; do not paraphrase from training. +The map is keyed by the question an agent or operator is trying to answer. Where the upstream repo lacks an anchor needed for clean linking, the convention is to request the anchor upstream rather than work around it with a deeper inline copy. ### By question -| If you are asking… | Go to | +| If you are asking… | Go to (upstream `.invariants`) | |---|---| -| What is the convention? | [Starter kit README](https://github.com/boorich/.invariants-starter-kit/blob/main/README.md) · [Landing page](https://boorich.github.io/.invariants-starter-kit/) | -| What does a dotfile look like? | [`.invariants.example`](https://github.com/boorich/.invariants-starter-kit/blob/main/.invariants.example) · Spec section on the [landing page](https://boorich.github.io/.invariants-starter-kit/#spec) | -| How are verdicts chosen? | [Conformance agent rule](https://github.com/boorich/.invariants-starter-kit/blob/main/.cursor/rules/conformance-agent.mdc) · [Verdict section](https://boorich.github.io/.invariants-starter-kit/#verdict) | -| How do I run the full loop locally? | [Try it](https://boorich.github.io/.invariants-starter-kit/#try) · `bash setup.sh` in the repo | -| Code vs markdown for agents? | README [Two layers](https://github.com/boorich/.invariants-starter-kit#two-layers-code-in-vecs-markdown-on-disk) · `·NAV` sentinels in `GLOSSARY.md` | -| Qdrant without Docker (macOS)? | [README — native install](https://github.com/boorich/.invariants-starter-kit#qdrant-without-docker-macos-power-users) | +| What is an invariant in this framework? | [Starter kit README](https://github.com/boorich/.invariants-starter-kit/blob/main/README.md) · [Landing — What](https://boorich.github.io/.invariants-starter-kit/#what) | +| What does the dotfile look like? | [`.invariants.example`](https://github.com/boorich/.invariants-starter-kit/blob/main/.invariants.example) · [Landing — Spec](https://boorich.github.io/.invariants-starter-kit/#spec) | +| How do I name an invariant? | Naming convention section *(anchor TBD upstream — coordinate with @boorich)* | +| How do I make an invariant testable? | `verify` hints in dotfile + [conformance agent](https://github.com/boorich/.invariants-starter-kit/blob/main/.cursor/rules/conformance-agent.mdc) | +| What is the lifecycle of an invariant — proposal → approval → enforcement → retirement? | Lifecycle section *(anchor TBD upstream)* | +| How is an invariant violation reported and triaged? | [Conformance agent](https://github.com/boorich/.invariants-starter-kit/blob/main/.cursor/rules/conformance-agent.mdc) · GitHub labels (`needs_triage` → `in_triage`) in starter kit README | +| How are invariants versioned and migrated? | Versioning section *(anchor TBD upstream)* · severity table on [landing — Verdict](https://boorich.github.io/.invariants-starter-kit/#verdict) | +| How does `.invariants` interact with ADRs in product repos? | [PR authoring — invariants impacted](https://github.com/ChainSafe/engineering-handbook/blob/main/workflows/pr-authoring.md) (handbook) + cascade in dotfile | +| How do I run the optional agent + code-index loop? | [Landing — Try it](https://boorich.github.io/.invariants-starter-kit/#try) · `bash setup.sh` in starter kit | ### By context +Where the handbook deep-links into `.invariants` from elsewhere: + | Handbook section | Upstream target | |---|---| -| `languages//architect.md` (every architect role) | This pointer page + product-repo `.invariants` files | -| `workflows/pr-authoring.md` (ADR templates) | "Invariants impacted" — cite assertion `id` from the cascade | -| Reviewer / architect skills | [`invariants-framework.md`](./invariants-framework.md) before architecture tasks | +| `languages//architect.md` (every architect role) | Per-language invariant section, e.g. concurrency invariants for the Rust architect, data-integrity invariants for the Daml architect — plus product-repo `.invariants` files | +| `workflows/pr-authoring.md` (ADR templates) | "Invariants impacted" template guidance — cite assertion `id` from the cascade | +| Reviewer skills — when a language reviewer needs to check whether an architectural invariant is violated | Reviewer-facing rules; architectural claims defer to dotfiles + [conformance agent](https://github.com/boorich/.invariants-starter-kit/blob/main/.cursor/rules/conformance-agent.mdc) | ## How to use this page -- **As an agent:** Before architecture or system-design work, consult the by-question table. Pull files from the [starter kit repo](https://github.com/boorich/.invariants-starter-kit) or product `.invariants` dotfiles. Do not invent assertion ids or severities. -- **As an operator:** When reviewing an ADR or design, verify threatened claims against the cascade. PASS/FAIL belongs in reports — never in the dotfile. -- **As a contributor:** Do not duplicate `.invariants` rules in handbook pages. Deep-link here and upstream. Coordinate anchor changes with [@boorich](https://github.com/boorich). +- **As an agent:** before any architecture or system-design task, consult the by-question table above. Fetch the upstream `.invariants` content for the entries that apply. Do not paraphrase upstream content from your training; pull the actual file. +- **As an operator:** when reviewing an architectural proposal (ADR, design doc, system design), use the deep-link table to verify the proposal addresses the relevant invariants. The `languages//architect.md` pages cite specific invariants per language; this page is the meta-index. +- **As a contributor adding architectural content to this handbook:** do not duplicate `.invariants` rules in your page. Deep-link them. If the upstream rule you need is not anchorable cleanly, coordinate with [@boorich](https://github.com/boorich) to add the heading, then link. + +## Inline `.invariants`-derived rules (for trivial-lookup cases only) + +To keep agents from chasing the link for every minor question, a small set of `.invariants`-derived rules is restated inline. This list is kept short on purpose — anything beyond a one-liner belongs upstream, not here. -## What not to put in `.invariants` +*Which rules earn an inline restatement versus a link-only entry is coordinated with [@boorich](https://github.com/boorich). The bar is deliberately high: only genuinely one-line, frequently-needed rules are restated here; everything else stays upstream.* -Issue numbers, "currently failing", fork labels, or temporary waivers. Forks are articulated in **conformance reports**, not in the dotfile. See the [landing page](https://boorich.github.io/.invariants-starter-kit/) and starter kit README. +**Do not put in dotfiles:** issue numbers, "currently failing", fork labels, or temporary waivers — see starter kit README and landing page. ## Coordination -[@boorich](https://github.com/boorich) maintains the upstream convention and is CODEOWNER for this pointer page (see [`../.github/CODEOWNERS`](../.github/CODEOWNERS)). When the starter kit restructures, update this map in the same PR. +[@boorich](https://github.com/boorich) is the maintainer of `.invariants` and the CODEOWNER for this pointer page (see [`../.github/CODEOWNERS`](../.github/CODEOWNERS)). Any change to the deep-link map or to the inline-rules section goes through him. Conversely, when the upstream repo restructures, the anchors here update — the pointer page is the contract between the handbook and the upstream repo. ## Related -- [`engineering-invariants.md`](./engineering-invariants.md) — general engineering invariants. `.invariants` is the complement for architecture. +- [`engineering-invariants.md`](./engineering-invariants.md) — general engineering invariants. `.invariants` is the domain-specific complement for architecture. - [`agent-era-invariants.md`](./agent-era-invariants.md) — agent-specific invariants; orthogonal to `.invariants`. -- [`../languages/`](../languages/) — architect pages defer to `.invariants` per the by-context table above. -- [`../references/sources.md`](../references/sources.md) — full catalog of external canonical sources. +- [`../languages/`](../languages/) — language-specific architect pages deep-link into `.invariants` per the by-context table above. +- [`../references/sources.md`](../references/sources.md) — full catalog of external canonical sources the handbook defers to. From f1e6a411fa1c0727e5304dc4e8af690d084d115d Mon Sep 17 00:00:00 2001 From: empea-careercriminal Date: Thu, 4 Jun 2026 17:40:01 +0200 Subject: [PATCH 3/5] Link pointer page to starter kit policy sections. Replace TBD rows with anchors for naming, lifecycle, and versioning; keep PR-COMMENT.md local-only. --- .gitignore | 3 +++ invariants/invariants-framework.md | 6 +++--- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/.gitignore b/.gitignore index 82a57c2..7bb5f7b 100644 --- a/.gitignore +++ b/.gitignore @@ -17,6 +17,9 @@ dictionary.dic .env.production.local .idea +# Local PR notes (not for repo) +PR-COMMENT.md + npm-debug.log* yarn-debug.log* yarn-error.log* diff --git a/invariants/invariants-framework.md b/invariants/invariants-framework.md index 462eda1..7cebf65 100644 --- a/invariants/invariants-framework.md +++ b/invariants/invariants-framework.md @@ -27,11 +27,11 @@ The map is keyed by the question an agent or operator is trying to answer. Where |---|---| | What is an invariant in this framework? | [Starter kit README](https://github.com/boorich/.invariants-starter-kit/blob/main/README.md) · [Landing — What](https://boorich.github.io/.invariants-starter-kit/#what) | | What does the dotfile look like? | [`.invariants.example`](https://github.com/boorich/.invariants-starter-kit/blob/main/.invariants.example) · [Landing — Spec](https://boorich.github.io/.invariants-starter-kit/#spec) | -| How do I name an invariant? | Naming convention section *(anchor TBD upstream — coordinate with @boorich)* | +| How do I name an invariant? | [Naming assertions](https://github.com/boorich/.invariants-starter-kit#naming-assertions) · [`.invariants.example`](https://github.com/boorich/.invariants-starter-kit/blob/main/.invariants.example) | | How do I make an invariant testable? | `verify` hints in dotfile + [conformance agent](https://github.com/boorich/.invariants-starter-kit/blob/main/.cursor/rules/conformance-agent.mdc) | -| What is the lifecycle of an invariant — proposal → approval → enforcement → retirement? | Lifecycle section *(anchor TBD upstream)* | +| What is the lifecycle of an invariant — proposal → approval → enforcement → retirement? | [Lifecycle of assertions](https://github.com/boorich/.invariants-starter-kit#lifecycle-of-assertions) | | How is an invariant violation reported and triaged? | [Conformance agent](https://github.com/boorich/.invariants-starter-kit/blob/main/.cursor/rules/conformance-agent.mdc) · GitHub labels (`needs_triage` → `in_triage`) in starter kit README | -| How are invariants versioned and migrated? | Versioning section *(anchor TBD upstream)* · severity table on [landing — Verdict](https://boorich.github.io/.invariants-starter-kit/#verdict) | +| How are invariants versioned and migrated? | [Versioning and migration](https://github.com/boorich/.invariants-starter-kit#versioning-and-migration) · [Verdict](https://boorich.github.io/.invariants-starter-kit/#verdict) | | How does `.invariants` interact with ADRs in product repos? | [PR authoring — invariants impacted](https://github.com/ChainSafe/engineering-handbook/blob/main/workflows/pr-authoring.md) (handbook) + cascade in dotfile | | How do I run the optional agent + code-index loop? | [Landing — Try it](https://boorich.github.io/.invariants-starter-kit/#try) · `bash setup.sh` in starter kit | From 112ff6d41c5afcfbcda0f6b75d706f0bd64f91e8 Mon Sep 17 00:00:00 2001 From: Peter Kalambet Date: Mon, 8 Jun 2026 10:59:56 +0200 Subject: [PATCH 4/5] fix merge error --- languages/solidity/architect.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/languages/solidity/architect.md b/languages/solidity/architect.md index 0f6c8a5..ffe1e4d 100644 --- a/languages/solidity/architect.md +++ b/languages/solidity/architect.md @@ -1,6 +1,6 @@ # Solidity Architect -Architectural guidance for Solidity (and EVM-adjacent) work at ChainSafe — [Sprinter](https://github.com/sprintertech) and the broader crypto/bridging surface. The architectural framework is `.invariance` (see the [pointer page](../../invariants/invariance-framework.md)); this page covers Solidity-specific shaping. +Architectural guidance for Solidity (and EVM-adjacent) work at ChainSafe — [Sprinter](https://github.com/sprintertech) and the broader crypto/bridging surface. The architectural framework is `.invariants` (see the [pointer page](../../invariants/invariants-framework.md)); this page covers Solidity-specific shaping. > **In one line:** Every Solidity decision is a security decision. Upgrade safety, reentrancy, and audit-readiness are first-class architectural concerns. From 73fa02ca318c2a2127dbb572825bd8c30fea2e45 Mon Sep 17 00:00:00 2001 From: Peter Kalambet Date: Mon, 8 Jun 2026 11:19:14 +0200 Subject: [PATCH 5/5] fix invariants links --- .lycheecache | 172 +++++++++++++++-------------- invariants/invariants-framework.md | 12 +- lychee.toml | 8 +- 3 files changed, 101 insertions(+), 91 deletions(-) diff --git a/.lycheecache b/.lycheecache index 9af9050..8b0485a 100644 --- a/.lycheecache +++ b/.lycheecache @@ -1,96 +1,108 @@ -https://github.com/ChainSafe/yarn-workspaces-typescript-template,200,1780908111 -https://docs.canton.network/appdev/tooling/ide-setup,200,1780907131 -https://docs.canton.network/appdev/modules/m6-limitations,200,1780907128 -https://docs.canton.network/appdev/reference/daml-language-reference,200,1780907131 -https://github.com/ChainSafe/canton-ci,200,1780907133 -https://go.dev/doc/effective_go,200,1780907127 -https://ziglang.org/documentation/master/#Style-Guide,200,1780907127 -https://docs.canton.network/appdev/modules/m6-overview,200,1780907130 -https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/configuring-tag-protection-rules,200,1780907128 -https://github.com/jorgef/engineeringladders,200,1780907135 -https://ziglang.org/learn/,200,1780907127 -https://docs.canton.network/appdev/modules/m3-contract-templates,200,1780907129 -https://github.com/ChainSafe/chainbridge-substrate,200,1780908111 -https://github.com/uber-go/mock,200,1780907146 -"https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@300;400;500&family=Fraunces:ital,wght@0,300;0,700;1,300&display=swap",200,1780907127 -https://github.com/ChainSafe/forest,200,1780908111 -https://github.com/ChainSafe/ssz,200,1780907152 +https://ziglang.org/documentation/master/,200,1780907127 +https://ziglang.org/documentation/master/std/,200,1780907127 https://effective-rust.com/generics.html,200,1780907127 +https://github.com/ChainSafe/mina-rs,200,1780907156 https://pkg.go.dev/std,200,1780907127 -https://docs.canton.network/appdev/deep-dives/smart-contract-upgrade,200,1780907133 +https://docs.canton.network/appdev/modules/m3-functional-programming,200,1780907129 +https://docs.canton.network/appdev/modules/m3-standard-library,200,1780907128 https://docs.canton.network/appdev/modules/m3-choices,200,1780907129 -https://docs.canton.network/appdev/modules/m3-working-with-time,200,1780907128 -https://github.com/hanabi1224,200,1780907145 -https://github.com/wemeetagain,200,1780907141 -https://effective-rust.com/documentation.html,200,1780907127 -https://github.com/ChainSafe/filsnap,200,1780907155 -https://forest.chainsafe.io/,200,1780907128 -https://github.com/matthewkeil,200,1780907146 -https://docs.canton.network/appdev/modules/m3-design-patterns,200,1780907131 -https://github.com/anthropics/skills,200,1780908111 -https://github.com/golang/mock,200,1780907150 +https://github.com/boorich/.invariants-starter-kit,200,1780910052 +https://github.com/cla-assistant/cla-assistant,200,1780907147 +https://doc.rust-lang.org/book/,200,1780907127 +https://github.com/boorich,200,1780907136 +https://docs.canton.network/appdev/modules/m6-overview,200,1780907130 +https://docs.canton.network/appdev/modules/m6-limitations,200,1780907128 +https://docs.canton.network/appdev/deep-dives/privacy-model,200,1780907131 +https://docs.canton.network/appdev/tooling/development-tools-overview,200,1780907131 +https://boorich.github.io/.invariants-starter-kit/#try,200,1780910052 https://github.com/ChainSafe/lodestar-z,200,1780907140 +https://docs.canton.network/appdev/modules/m3-design-patterns,200,1780907131 +https://boorich.github.io/.invariants-starter-kit/#spec,200,1780910052 +https://ziglang.org/learn/build-system/,200,1780907127 +https://github.com/ChainSafe/forest/blob/main/AI_POLICY.md,200,1780907134 https://golangci-lint.run/usage/linters/#enabled-by-default,200,1780907127 -https://www.endoflineblog.com/oneflow-a-git-branching-model-and-workflow,200,1780907127 -https://chainsafe.io/,200,1780907128 -https://docs.canton.network/appdev/modules/m3-contract-keys,200,1780907129 -https://github.com/ChainSafe/eslint-config,200,1780907147 -https://docs.canton.network/appdev/reference/daml-lf-reference,200,1780907131 -https://effective-rust.com/,200,1780907127 -https://github.com/salindne,200,1780908111 +https://docs.canton.network/appdev/modules/m3-contract-templates,200,1780907129 +https://www.notion.so/chainsafe/Core-Concepts-v1-0-1610247189c949fa9692de950518ac53,200,1780907127 +https://github.com/ChainSafe/bls,200,1780907155 +https://github.com/golang/mock,200,1780907150 https://www.notion.so/chainsafe/Educational-Budget-c0cc6c8da3c74c6ead5f866d2fced452,200,1780907127 -https://github.com/sqhell,200,1780907140 -https://gaming.chainsafe.io/,200,1780907128 -https://docs.canton.network/appdev/deep-dives/privacy-model,200,1780907131 -https://docs.canton.network/appdev/modules/m6-writing-first-upgrade,200,1780907130 -https://github.com/sprintertech,200,1780907153 +https://github.com/ChainSafe/yarn-workspaces-typescript-template,200,1780908111 +https://github.com/LesnyRumcajs,200,1780907140 +https://boorich.github.io/.invariants-starter-kit/#verdict,200,1780910052 +https://docs.canton.network/appdev/modules/m3-contract-keys,200,1780907129 +https://github.com/boorich/.invariants-starter-kit#lifecycle-of-assertions,200,1780910052 +https://forest.chainsafe.io/,200,1780907128 +https://docs.canton.network/,200,1780907127 +https://go.dev/doc/effective_go,200,1780907127 +https://github.com/boorich/.invariants-starter-kit/blob/master/README.md,200,1780910226 +https://boristane.com/blog/how-i-use-claude-code/,200,1780907127 https://ziglang.org/,200,1780907127 -https://github.com/kalambet,200,1780908110 -https://effective-rust.com/semver.html,200,1780907127 -https://daml-autopilot.chainsafe.io/,200,1780907127 -https://docs.canton.network/appdev/modules/m3-interfaces,200,1780907130 -https://docs.canton.network/appdev/tooling/development-tools-overview,200,1780907131 -https://www.sprinter.tech/,200,1780907128 -https://github.com/cla-assistant/cla-assistant,200,1780907147 -https://github.com/ChainSafe/mina-rs,200,1780907156 -https://effectivepython.com/,200,1780907127 -https://docs.astral.sh/ruff/,200,1780907127 -https://docs.canton.network/appdev/modules/m6-upgrade-compatibility,200,1780907128 https://github.com/canton-network/cf-docs,200,1780907139 -https://doc.rust-lang.org/book/ch14-02-publishing-to-crates-io.html,200,1780907127 -https://github.com/ChainSafe/engineering-handbook/blob/main/README.md,200,1780907135 +https://github.com/ChainSafe/forest,200,1780908111 +https://docs.canton.network/appdev/modules/m3-working-with-time,200,1780907128 +https://www.sprinter.tech/,200,1780907128 https://docs.canton.network/appdev/modules/m5-testing-strategies,200,1780907130 -https://docs.canton.network/appdev/modules/m5-ci-cd-integration,200,1780907131 -https://docs.canton.network/appdev/modules/m3-standard-library,200,1780907128 -https://docs.canton.network/,200,1780907127 -https://llmstxt.org/,200,1780907127 +https://daml-autopilot.chainsafe.io/,200,1780907127 +https://docs.canton.network/appdev/reference/daml-language-reference,200,1780907131 +https://docs.canton.network/appdev/deep-dives/smart-contract-upgrade,200,1780907133 +https://github.com/ChainSafe/ssz,200,1780907152 +https://effective-rust.com/wildcard.html,200,1780907127 +https://effective-rust.com/macros.html,200,1780907127 +https://docs.astral.sh/uv/,200,1780907127 +https://github.com/joshdougall,200,1780907133 +https://github.com/sqhell,200,1780907140 +https://github.com/ChainSafe/lodestar,200,1780907148 https://github.com/ghostty-org/ghostty,200,1780907134 +https://github.com/ChainSafe/engineering-handbook/blob/main/README.md,200,1780907135 +https://github.com/boorich/.invariants-starter-kit#naming-assertions,200,1780910052 +https://github.com/wemeetagain,200,1780907141 +https://docs.canton.network/appdev/modules/m3-testing,200,1780907130 +https://github.com/boorich/.invariants-starter-kit/blob/master/.cursor/rules/conformance-agent.mdc,200,1780910219 +https://docs.canton.network/appdev/modules/m7-security,200,1780907128 +https://github.com/boorich/.invariants-starter-kit#versioning-and-migration,200,1780910052 +https://github.com/kalambet,200,1780908110 +https://docs.canton.network/appdev/reference/daml-lf-reference,200,1780907131 +https://boorich.github.io/.invariants-starter-kit/#what,200,1780910052 https://github.com/ChainSafe/canton-ci#current-known-issues,200,1780907133 +https://docs.canton.network/appdev/modules/m3-interfaces,200,1780907130 +https://golangci-lint.run/usage/linters/,200,1780907127 +https://docs.canton.network/appdev/modules/m3-dev-environment,200,1780907128 +https://doc.rust-lang.org/book/ch14-02-publishing-to-crates-io.html,200,1780907127 +https://github.com/ChainSafe/gossamer,200,1780907146 https://docs.canton.network/appdev/modules/m3-language-fundamentals,200,1780907129 -https://docs.canton.network/llms.txt,200,1780907127 -https://ziglang.org/documentation/master/,200,1780907127 -https://github.com/ChainSafe/forest/blob/main/AI_POLICY.md,200,1780907134 -https://github.com/LesnyRumcajs,200,1780907140 +https://docs.canton.network/appdev/modules/m6-writing-first-upgrade,200,1780907130 +https://github.com/boorich/.invariants-starter-kit/blob/master/.invariants.example,200,1780910227 +https://github.com/ChainSafe/filsnap,200,1780907155 https://github.com/ChainSafe/web3.js,200,1780907157 -https://effective-rust.com/macros.html,200,1780907127 -https://docs.canton.network/appdev/modules/m7-security,200,1780907128 -https://docs.canton.network/appdev/modules/m3-functional-programming,200,1780907129 -https://effective-rust.com/wildcard.html,200,1780907127 -https://doc.rust-lang.org/book/,200,1780907127 -https://docs.canton.network/appdev/modules/m3-dev-environment,200,1780907128 +https://github.com/ChainSafe/canton-ci,200,1780907133 +https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/configuring-tag-protection-rules,200,1780907128 +https://docs.canton.network/appdev/modules/m5-ci-cd-integration,200,1780907131 +https://github.com/ChainSafe/eslint-config,200,1780907147 +https://ziglang.org/learn/,200,1780907127 +https://boorich.github.io/.invariants-starter-kit/,200,1780910050 +https://effective-rust.com/,200,1780907127 +https://effective-rust.com/semver.html,200,1780907127 +https://www.endoflineblog.com/oneflow-a-git-branching-model-and-workflow,200,1780907127 +https://llmstxt.org/,200,1780907127 +"https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@300;400;500&family=Fraunces:ital,wght@0,300;0,700;1,300&display=swap",200,1780907127 +https://effectivepython.com/,200,1780907127 +https://docs.canton.network/appdev/tooling/ide-setup,200,1780907131 +https://github.com/bslatkin/effectivepython,200,1780907148 +https://github.com/uber-go/mock,200,1780907146 +https://gaming.chainsafe.io/,200,1780907128 +https://github.com/hanabi1224,200,1780907145 +https://github.com/salindne,200,1780908111 +https://ziglang.org/documentation/master/#Style-Guide,200,1780907127 +https://github.com/jorgef/engineeringladders,200,1780907135 +https://docs.canton.network/appdev/modules/m6-upgrade-compatibility,200,1780907128 +https://github.com/ChainSafe/chainbridge-substrate,200,1780908111 https://daml-autopilot.chainsafe.io/setup,200,1780907127 -https://github.com/boorich,200,1780907136 -https://www.notion.so/chainsafe/Core-Concepts-v1-0-1610247189c949fa9692de950518ac53,200,1780907127 -https://github.com/ChainSafe/bls,200,1780907155 -https://ziglang.org/learn/build-system/,200,1780907127 +https://docs.canton.network/llms.txt,200,1780907127 +https://chainsafe.io/,200,1780907128 +https://github.com/matthewkeil,200,1780907146 +https://github.com/sprintertech,200,1780907153 https://golangci-lint.run/,200,1780907127 -https://github.com/bslatkin/effectivepython,200,1780907148 -https://ziglang.org/documentation/master/std/,200,1780907127 -https://github.com/joshdougall,200,1780907133 -https://boristane.com/blog/how-i-use-claude-code/,200,1780907127 -https://docs.astral.sh/uv/,200,1780907127 +https://github.com/anthropics/skills,200,1780908111 +https://effective-rust.com/documentation.html,200,1780907127 +https://docs.astral.sh/ruff/,200,1780907127 https://docs.canton.network/appdev/modules/m3-authorization,200,1780907128 -https://github.com/ChainSafe/lodestar,200,1780907148 -https://github.com/ChainSafe/gossamer,200,1780907146 -https://golangci-lint.run/usage/linters/,200,1780907127 -https://docs.canton.network/appdev/modules/m3-testing,200,1780907130 diff --git a/invariants/invariants-framework.md b/invariants/invariants-framework.md index 7cebf65..169a0e3 100644 --- a/invariants/invariants-framework.md +++ b/invariants/invariants-framework.md @@ -25,12 +25,12 @@ The map is keyed by the question an agent or operator is trying to answer. Where | If you are asking… | Go to (upstream `.invariants`) | |---|---| -| What is an invariant in this framework? | [Starter kit README](https://github.com/boorich/.invariants-starter-kit/blob/main/README.md) · [Landing — What](https://boorich.github.io/.invariants-starter-kit/#what) | -| What does the dotfile look like? | [`.invariants.example`](https://github.com/boorich/.invariants-starter-kit/blob/main/.invariants.example) · [Landing — Spec](https://boorich.github.io/.invariants-starter-kit/#spec) | -| How do I name an invariant? | [Naming assertions](https://github.com/boorich/.invariants-starter-kit#naming-assertions) · [`.invariants.example`](https://github.com/boorich/.invariants-starter-kit/blob/main/.invariants.example) | -| How do I make an invariant testable? | `verify` hints in dotfile + [conformance agent](https://github.com/boorich/.invariants-starter-kit/blob/main/.cursor/rules/conformance-agent.mdc) | +| What is an invariant in this framework? | [Starter kit README](https://github.com/boorich/.invariants-starter-kit/blob/master/README.md) · [Landing — What](https://boorich.github.io/.invariants-starter-kit/#what) | +| What does the dotfile look like? | [`.invariants.example`](https://github.com/boorich/.invariants-starter-kit/blob/master/.invariants.example) · [Landing — Spec](https://boorich.github.io/.invariants-starter-kit/#spec) | +| How do I name an invariant? | [Naming assertions](https://github.com/boorich/.invariants-starter-kit#naming-assertions) · [`.invariants.example`](https://github.com/boorich/.invariants-starter-kit/blob/master/.invariants.example) | +| How do I make an invariant testable? | `verify` hints in dotfile + [conformance agent](https://github.com/boorich/.invariants-starter-kit/blob/master/.cursor/rules/conformance-agent.mdc) | | What is the lifecycle of an invariant — proposal → approval → enforcement → retirement? | [Lifecycle of assertions](https://github.com/boorich/.invariants-starter-kit#lifecycle-of-assertions) | -| How is an invariant violation reported and triaged? | [Conformance agent](https://github.com/boorich/.invariants-starter-kit/blob/main/.cursor/rules/conformance-agent.mdc) · GitHub labels (`needs_triage` → `in_triage`) in starter kit README | +| How is an invariant violation reported and triaged? | [Conformance agent](https://github.com/boorich/.invariants-starter-kit/blob/master/.cursor/rules/conformance-agent.mdc) · GitHub labels (`needs_triage` → `in_triage`) in starter kit README | | How are invariants versioned and migrated? | [Versioning and migration](https://github.com/boorich/.invariants-starter-kit#versioning-and-migration) · [Verdict](https://boorich.github.io/.invariants-starter-kit/#verdict) | | How does `.invariants` interact with ADRs in product repos? | [PR authoring — invariants impacted](https://github.com/ChainSafe/engineering-handbook/blob/main/workflows/pr-authoring.md) (handbook) + cascade in dotfile | | How do I run the optional agent + code-index loop? | [Landing — Try it](https://boorich.github.io/.invariants-starter-kit/#try) · `bash setup.sh` in starter kit | @@ -43,7 +43,7 @@ Where the handbook deep-links into `.invariants` from elsewhere: |---|---| | `languages//architect.md` (every architect role) | Per-language invariant section, e.g. concurrency invariants for the Rust architect, data-integrity invariants for the Daml architect — plus product-repo `.invariants` files | | `workflows/pr-authoring.md` (ADR templates) | "Invariants impacted" template guidance — cite assertion `id` from the cascade | -| Reviewer skills — when a language reviewer needs to check whether an architectural invariant is violated | Reviewer-facing rules; architectural claims defer to dotfiles + [conformance agent](https://github.com/boorich/.invariants-starter-kit/blob/main/.cursor/rules/conformance-agent.mdc) | +| Reviewer skills — when a language reviewer needs to check whether an architectural invariant is violated | Reviewer-facing rules; architectural claims defer to dotfiles + [conformance agent](https://github.com/boorich/.invariants-starter-kit/blob/master/.cursor/rules/conformance-agent.mdc) | ## How to use this page diff --git a/lychee.toml b/lychee.toml index 0e36fd5..c011005 100644 --- a/lychee.toml +++ b/lychee.toml @@ -55,15 +55,13 @@ exclude = [ '(^|//)([^/]+\.)?chainsafe\.tech\b', '^https://forms\.gle', '^https://github.com/ChainSafe/infrastructure-general', - #TODO: till merge to main - '^https://raw\.githubusercontent\.com\/ChainSafe\/engineering-handbook\/main' + # TODO: disabling link checker for the main repo till merge to main + '^https://raw\.githubusercontent\.com\/ChainSafe\/engineering-handbook\/main', + '^https://github\.com\/ChainSafe\/engineering-handbook\/blob\/main' ] # No excluded paths — all markdown is in scope. exclude_path = [ - # TODO: till we mrege to main - # For now, skip link-checking the llms.txt file till we merge it into the main branch. - "./llms.txt" ] ###########