@skill-graph/cli 0.5.6

package/examples/tests/v3-1-skos-fixture/SKILL.md

@@ -0,0 +1,93 @@
+---
+schema_version: 4
+name: v3-1-skos-fixture
+description: Test fixture exercising v3.1 SKOS predicates (related, broader, narrower) and the ADR 0006 split between boundary (routing-layer) and disjoint_with (OWL class-disjointness). Used by scripts/__tests__/test-v3-1-skos-runtime.js to verify that the manifest generator, lint, and router all recognize the full predicate set. Not a production skill.
+version: 1.0.0
+type: capability
+category: testing
+scope: portable
+owner: skill-graph-maintainer
+freshness: 2026-05-04
+license: MIT
+stability: experimental
+
+triggers:
+  - test fixture
+keywords:
+  - fixture
+  - v3-1
+  - SKOS
+  - predicate
+examples:
+  - "Used by scripts/__tests__/test-v3-1-skos-runtime.js to assert manifest entries"
+  - "Used by scripts/skill-lint.js relation-target test (related/broader/narrower)"
+  - "Used by scripts/skill-graph-route.js Stage 4b broader-recall test"
+anti_examples:
+  - "DO NOT use as a real authored skill — fixture only"
+
+relations:
+  related:
+    - documentation
+    - testing-strategy
+  broader:
+    - debugging
+  narrower:
+    - a11y
+  boundary:
+    - skill: skill-router
+      reason: "skill-router owns dispatch decisions; this fixture only exercises predicates"
+  disjoint_with:
+    - skill: refactor
+      reason: "Formal OWL example — fixture and refactor name disjoint conceptual classes"
+  verify_with:
+    - lint-overlay
+  depends_on:
+    - graph-audit
+
+eval_artifacts: none
+eval_state: untested
+routing_eval: absent
+
+drift_check:
+  last_verified: 2026-05-04
+---
+
+# v3.1 SKOS Fixture
+
+> Test fixture exercising the full v3.1 predicate set. Not a production skill.
+
+## Domain Context
+
+This fixture exists to verify that the runtime — `generate-manifest.js`, `skill-lint.js`,
+`skill-graph-route.js`, and the lint-target resolver — iterates the complete v3.1 predicate
+set defined in ADR 0001 (SKOS additions: `related`, `broader`, `narrower`) and ADR 0006
+(`boundary` canonical for routing-layer; `disjoint_with` separate orthogonal relation
+for formal OWL class-disjointness).
+
+The companion test `scripts/__tests__/test-v3-1-skos-runtime.js` builds a manifest entry
+from this file and asserts every predicate above appears in the resulting `relations`
+block, with relation-target validation passing for all eight references.
+
+## Coverage
+
+Predicates exercised:
+
+- `related` — symmetric SKOS associative relation (skos:related)
+- `broader` — SKOS generalisation (skos:broader); triggers Stage 4b parent recall in router
+- `narrower` — SKOS specialisation (skos:narrower)
+- `boundary` — routing-layer asymmetric handoff (sg:disjointOwnership)
+- `disjoint_with` — formal OWL class-disjointness (owl:disjointWith)
+- `verify_with` — PROV-O informational influence (prov:wasInformedBy)
+- `depends_on` — DCMI requirement (dcterms:requires)
+
+`adjacent` is intentionally NOT exercised here — that's covered by the back-compat
+fixture (a separate test asserting the deprecated alias still validates).
+
+## Workflow
+
+This skill has no workflow — it is a fixture, not a procedure.
+
+## Verification
+
+`scripts/__tests__/test-v3-1-skos-runtime.js` exits 0 only when this fixture round-trips
+cleanly through the manifest generator and lint relation-target check.

package/marketplace/README.md

@@ -0,0 +1,17 @@
+# Skill Graph Marketplace Export
+
+This directory is generated from the canonical Skill Metadata Protocol source in `skills/`.
+Do not edit generated files here by hand; run `node scripts/export-marketplace-skills.js` from the canonical repo.
+
+Canonical source repo: https://github.com/jacob-balslev/skill-graph
+Release target repo: jacob-balslev/skills
+Generated public skills: 140
+
+Each skill under `skills/<name>/SKILL.md` is a plain Agent Skills-compatible export.
+Protocol fields are preserved as string values under `metadata`, with factual Skill Graph provenance.
+
+After the release target is published, install with:
+
+```bash
+npx skills add jacob-balslev/skills
+```

package/marketplace/skills/a11y/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: a11y
+description: "Use when building or reviewing interactive UI, forms, navigation, or dynamic content. Covers semantic HTML, keyboard access, focus management, labeling, state-change announcement, and reduced-motion / high-contrast preferences. Do NOT use for color-palette creation, visual branding, feedback-state staging, or prose reading-level accessibility - those belong to `visual-design-foundations`, `interaction-feedback`, and documentation respectively."
+license: MIT
+compatibility: "Markdown, Git, any web stack"
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"quality\",\"domain\":\"quality/accessibility\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-04-18\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-04-18\\\\\\\"}\",\"eval_artifacts\":\"present\",\"eval_state\":\"passing\",\"routing_eval\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"accessibility\\\\\\\",\\\\\\\"a11y\\\\\\\",\\\\\\\"keyboard navigation\\\\\\\",\\\\\\\"screen reader\\\\\\\",\\\\\\\"focus management\\\\\\\",\\\\\\\"keyboard not working\\\\\\\",\\\\\\\"tab order\\\\\\\",\\\\\\\"missing aria label\\\\\\\",\\\\\\\"screen reader says\\\\\\\",\\\\\\\"reduced motion\\\\\\\",\\\\\\\"high contrast\\\\\\\",\\\\\\\"semantic html\\\\\\\",\\\\\\\"form labels\\\\\\\",\\\\\\\"form fields\\\\\\\",\\\\\\\"aria-label\\\\\\\",\\\\\\\"assistive tech\\\\\\\",\\\\\\\"assistive technology\\\\\\\",\\\\\\\"accessible labels\\\\\\\",\\\\\\\"proper labels\\\\\\\"]\",\"triggers\":\"[\\\\\\\"a11y-skill\\\\\\\"]\",\"paths\":\"[\\\\\\\"**/*.{html,tsx,jsx,vue,svelte}\\\\\\\",\\\\\\\"**/*.css\\\\\\\",\\\\\\\"!**/*.test.{ts,tsx,js,jsx}\\\\\\\",\\\\\\\"!**/dist/**\\\\\\\",\\\\\\\"!**/node_modules/**\\\\\\\"]\",\"examples\":\"[\\\\\\\"this modal is keyboard-trapped — users can't Escape to close it\\\\\\\",\\\\\\\"screen reader doesn't announce when the form validation state changes\\\\\\\",\\\\\\\"add proper labels to these form fields so assistive tech can read them\\\\\\\",\\\\\\\"review this dropdown menu for arrow-key navigation and focus return\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"rewrite this error message at a 6th-grade reading level\\\\\\\",\\\\\\\"clean up this accessibility code without changing how it behaves\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"refactor\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"refactor is behavior-preserving code modification; a11y is observable user-facing behavior\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"diagnosis\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"diagnosis classifies failure symptoms (Logic / Runtime / Performance / etc.) for triage; a11y owns assistive-tech behavior. The phrase 'rewrite this error message...' is a documentation/UX concern, not a diagnosis or a11y concern — diagnosis is named here so the router excludes it from a11y's positive scope.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"visual-design-foundations\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"visual-design-foundations owns palette, typography, spacing, and visual craft; a11y owns whether the resulting interaction is perceivable, operable, understandable, and robust\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"interaction-feedback\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"interaction-feedback owns feedback-state staging; a11y owns whether those state changes are announced and operable\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"interaction-patterns\\\\\\\",\\\\\\\"form-ux-architecture\\\\\\\",\\\\\\\"interaction-feedback\\\\\\\",\\\\\\\"design-system-architecture\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"testing-strategy\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/a11y/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/a11y/SKILL.md
+---
+
+# Accessibility
+
+## Coverage
+
+- Semantic HTML: choosing the right primitive elements so structure is meaningful to assistive technology
+- Keyboard access: making every interaction reachable and operable without a pointing device
+- Focus management: keeping focus visible, predictable, and correctly placed after navigation and state changes
+- Labeling and naming: ensuring every interactive element has a programmatic name that matches its visible label
+- State and change announcement: communicating dynamic updates (loading, errors, success) to assistive technology
+- Reduced-motion and high-contrast preferences: respecting user settings that affect interaction perception
+
+## Philosophy
+
+Accessible interaction is structural, not cosmetic. It is decided by the primitive you picked, the focus order you wrote, and the label that ships or doesn't — not by the audit that runs after. Teams that treat accessibility as a finishing pass pay for it twice: once in remediation work that was cheaper to avoid, and again when assistive-technology users hit the failure and bounce. The correct default is to build with those users in scope from the first commit, not after the first lawsuit.
+
+## Primitive Selection
+
+The single highest-leverage accessibility decision is picking the right HTML primitive before styling. A wrong primitive cannot be rescued by ARIA; the right primitive usually needs no ARIA at all.
+
+| User intent                          | Correct primitive                               | Wrong primitives (common mistakes)                      |
+| ------------------------------------ | ----------------------------------------------- | ------------------------------------------------------- |
+| Trigger an action on the same page   | `<button type="button">`                        | `<a href="#">`, `<div onclick>`, `<span role="button">` |
+| Navigate to a different URL          | `<a href="…">`                                  | `<button onclick=navigate>`, `<div onclick>`            |
+| Group related form controls          | `<fieldset>` + `<legend>`                       | `<div>` with a heading above it                         |
+| Label a form control                 | `<label for="…">` (or wrapping `<label>`)       | `<div>` text next to the input, `placeholder` only      |
+| Show a collapsible section           | `<details>` + `<summary>`                       | `<div>` with JS toggle and no ARIA                      |
+| Present tabular data                 | `<table>` + `<th scope="…">`                    | `<div>` grid, CSS grid with no semantic role            |
+| Announce a status change             | `<output>` or `role="status"` live region       | Toast that only renders visually                        |
+| Interactive widget not covered above | Native element + tested keyboard + ARIA pattern | Custom `<div>` with ad-hoc `role` and handlers          |
+
+### When ARIA is appropriate
+
+Only when no native primitive fits the interaction, and only when you also ship the keyboard behavior that matches the role. Adding `role="button"` to a `<div>` without Enter/Space handlers is worse than either the correct `<button>` or the untyped `<div>` alone.
+
+## Evals
+
+This skill ships a comprehension-eval artifact at [`examples/evals/a11y.json`](https://github.com/jacob-balslev/skill-graph/blob/main/examples/evals/a11y.json). The `Verification` checklist below is the authoring gate for a new interactive component; the eval file is how this skill is graded by `scripts/skill-audit.js --graded`. Do not conflate them — the checklist is for implementers, the eval is for the grader.
+
+## Verification
+
+- [ ] Interactive elements use the right semantic primitives
+- [ ] Keyboard-only flows remain usable
+- [ ] Focus is visible and lands in the correct place
+- [ ] Labels and state changes are perceivable
+- [ ] User preferences (reduced motion, high contrast) are respected
+
+## Do NOT Use When
+
+| Use instead     | When                                                                                                     |
+| --------------- | -------------------------------------------------------------------------------------------------------- |
+| `documentation` | The task is prose structure or reading-level clarity, not interaction accessibility                      |
+| `refactor`      | The task is behavior-preserving code cleanup — refactoring does not change what assistive tech perceives |

package/marketplace/skills/acid-fundamentals/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: acid-fundamentals
+description: "Use when reasoning about the four ACID properties of database transactions — Atomicity, Consistency, Isolation, Durability — as foundational concepts beneath any transactional system: what each property formally guarantees, the difference between the property the database claims and the property the application gets (depending on isolation level, replication mode, and configuration), the relationship between ACID and BASE (the alternative model in many NoSQL systems), why 'C' is the most contested letter (database consistency vs application invariants), and the historical record (Härder & Reuter 1983, the Gray-Reuter transaction model, Gray's Turing lecture). Do NOT use for choosing isolation levels for a specific workload (use transaction-isolation), distributed-system CAP tradeoffs (use cap-theorem-tradeoffs), database query design (use query-optimization), or zero-downtime migration mechanics (use database-migration)."
+license: MIT
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"engineering/data\",\"scope\":\"reference\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-16\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-16\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"comprehension_state\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"ACID\\\\\\\",\\\\\\\"atomicity\\\\\\\",\\\\\\\"consistency\\\\\\\",\\\\\\\"isolation\\\\\\\",\\\\\\\"durability\\\\\\\",\\\\\\\"transaction\\\\\\\",\\\\\\\"BASE\\\\\\\",\\\\\\\"Härder Reuter\\\\\\\",\\\\\\\"Gray transaction model\\\\\\\",\\\\\\\"transactional guarantee\\\\\\\"]\",\"triggers\":\"[\\\\\\\"is this database ACID\\\\\\\",\\\\\\\"what does consistency mean\\\\\\\",\\\\\\\"ACID vs BASE\\\\\\\",\\\\\\\"is my transaction atomic\\\\\\\",\\\\\\\"what's the durability guarantee\\\\\\\"]\",\"examples\":\"[\\\\\\\"explain what ACID guarantees a database does and does not provide to the application\\\\\\\",\\\\\\\"decide whether ACID or BASE is the right model for a new system\\\\\\\",\\\\\\\"diagnose a data-loss incident — likely a durability or atomicity failure\\\\\\\",\\\\\\\"explain why the 'C' in ACID is not the same as application consistency\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"choose an isolation level for a workload (use transaction-isolation)\\\\\\\",\\\\\\\"reason about availability vs consistency in a distributed system (use cap-theorem-tradeoffs)\\\\\\\",\\\\\\\"design a database schema (use data-modeling)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"transaction-isolation\\\\\\\",\\\\\\\"cap-theorem-tradeoffs\\\\\\\",\\\\\\\"data-modeling\\\\\\\",\\\\\\\"replication-patterns\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"transaction-isolation\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"transaction-isolation owns the choice and semantics of isolation levels (read uncommitted, read committed, repeatable read, serializable, snapshot) — the 'I' of ACID specifically as a tunable. This skill owns ACID as the four-property foundational frame; transaction-isolation owns one of the four in operational depth.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"cap-theorem-tradeoffs\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"cap-theorem-tradeoffs owns the distributed-systems frame (consistency, availability, partition tolerance) which uses 'consistency' in a different sense than the C in ACID. This skill owns the single-system transactional frame; cap-theorem-tradeoffs owns the distributed frame; conflating them is the most common misconception in this space.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"data-modeling\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"data-modeling owns schema design and entity structure; this skill owns the transactional-guarantee semantics that any data model relies on at runtime.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"replication-patterns\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"replication-patterns owns the patterns for keeping multiple replicas in agreement; this skill owns the single-node transactional model from which distributed replication is a generalization (and often a relaxation of).\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"transaction-isolation\\\\\\\",\\\\\\\"cap-theorem-tradeoffs\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"ACID is to a database transaction what the four corners of a legal contract are to an agreement — Atomicity is the signing block (all parties sign together or no contract exists), Consistency is the boilerplate clauses (every clause must be satisfied for the contract to be valid), Isolation is the negotiating-room rule (other negotiations cannot read your draft until both sides initial each page), and Durability is the safe in the law office (once signed, the contract survives the office burning down).\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"ACID is the acronym for four properties that a database transaction either provides or does not provide, defining the contract between the database and the application using it: Atomicity (the transaction either entirely happens or entirely does not — there is no partial state visible after a failure), Consistency (the transaction takes the database from one valid state to another valid state per the database's defined integrity constraints), Isolation (concurrent transactions do not see each other's intermediate states; each transaction observes the database as if it were the only transaction), Durability (once the transaction commits, its effects survive any subsequent failure including power loss). The four properties were codified by Härder and Reuter (1983) based on Jim Gray's earlier transaction model and have become the foundational vocabulary for relational and many NoSQL database systems. The strategic value of the ACID frame is that it names the four orthogonal guarantees the application can rely on, so that when a database advertises 'ACID compliance' or claims to relax some property, the conversation has precise vocabulary.\\\\\\\",\\\\\\\"mental_model\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"purpose\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"boundary\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"taxonomy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"analogy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"misconception\\\\\\\":\\\\\\\"|\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/acid-fundamentals/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/acid-fundamentals/SKILL.md
+---
+
+# ACID Fundamentals
+
+## Coverage
+
+The four foundational transactional properties — Atomicity, Consistency, Isolation, Durability — that define the contract between a database and the application using it. Covers what each property formally guarantees, the implementation mechanisms underneath each (write-ahead logging for atomicity; locking and MVCC for isolation; constraint checking for consistency; synchronous storage flush for durability), the configuration-dependent strength of each property, the BASE alternative model for systems that trade ACID guarantees for availability, the C-of-ACID vs C-of-CAP distinction that is the most-frequently-confused concept in the space, and the historical record from Gray's transaction model through Härder & Reuter's 1983 formalization.
+
+## Philosophy
+
+ACID is the precise vocabulary the database industry uses to describe transactional guarantees. Before ACID, claims were vague; after ACID, a system's behavior on each of four orthogonal axes is the conversation. The strategic value of the frame is *not* the acronym itself but the discipline of asking, for any database in any configuration, what each property actually guarantees and what the application can rely on.
+
+The frame's defining property is that it names four *orthogonal* axes. A system can be atomic without being isolated; it can be durable without being consistent in the CAP sense; it can be consistent (database constraints satisfied) without being consistent across replicas. The four-letter frame is not a one-dimensional rating; it is a vector.
+
+The discipline is in the configuration. "Postgres is ACID" is a vague claim; "Postgres at read committed isolation with synchronous_commit on with foreign-key constraints enforced gives us A, I (at read-committed level), D, and C" is the precise statement. Knowing what your specific database guarantees in your specific configuration is operational hygiene; assuming the default is a class of incident.
+
+## The Four Properties — Precise Definitions
+
+| Property | Guarantee | Implementation |
+|---|---|---|
+| Atomicity | All-or-nothing per transaction; no partial state visible after failure | Write-ahead logging + rollback/redo |
+| Consistency | Database integrity constraints satisfied across the transaction | Foreign keys, NOT NULL, unique indexes, CHECK constraints, triggers |
+| Isolation | Concurrent transactions appear serialized | Locking, MVCC, serializable snapshot isolation |
+| Durability | Committed effects survive failure | Synchronous WAL flush, replication to durable storage |
+
+Each property is graded. Atomicity is essentially binary. Isolation has five+ levels (see `transaction-isolation`). Durability has multiple configurations (local sync, local async, replicated sync, quorum). Consistency has database-level rules vs application-level rules.
+
+## The Two C's — ACID vs CAP
+
+| Property | What it means | Example |
+|---|---|---|
+| ACID Consistency | Database integrity constraints satisfied | FK reference resolves; UNIQUE constraint holds |
+| CAP Consistency | All replicas agree on the current value | All replicas return the same balance for account #1234 |
+
+A database can be ACID-Consistent and CAP-Inconsistent (constraints hold; replicas disagree). A database can be CAP-Consistent and ACID-Inconsistent (replicas agree; foreign key was violated). They are different concepts with the same letter and are the most-confused pair in the space.
+
+## ACID vs BASE
+
+| Property | ACID | BASE |
+|---|---|---|
+| A | Atomicity per transaction | Basically Available |
+| C | Database-level Consistency | Soft state |
+| I | Isolation between concurrent transactions | (no I in BASE) |
+| D | Durability | Eventually consistent |
+| Trade | Strong guarantees, limited throughput/availability under partition | High throughput/availability, weaker correctness guarantees |
+| Typical use | Transactional cores: orders, payments, accounts | High-throughput non-transactional: streams, analytics, caches |
+| Examples | Postgres, Oracle, SQL Server, MongoDB transactions | Cassandra, Riak (default), DynamoDB (default) |
+
+Most production architectures use both, picking per component.
+
+## Configuration Matters
+
+Three configuration knobs that change what your database actually guarantees:
+
+| Knob | Default in Postgres | Effect when changed |
+|---|---|---|
+| `synchronous_commit` | `on` (durable) | `off` → commit acknowledged before WAL flush; last few commits lost on crash |
+| Isolation level | `read committed` | `serializable` is strongest; `read uncommitted` allows dirty reads |
+| Replication mode | none | Synchronous replication = D guarantees include replica; async = primary-only |
+
+Knowing your production configuration — not assuming the default — is operational hygiene.
+
+## Verification
+
+After applying this skill, verify:
+- [ ] The team can name what each ACID property guarantees and what it does not, distinct from the CAP properties.
+- [ ] The current database's configuration is known: isolation level, durability config, replication mode. The team is not relying on assumed defaults.
+- [ ] ACID's C and CAP's C are distinguished in design discussions. Using "consistency" without qualifier produces confused decisions.
+- [ ] Application-level invariants (business rules) are recognized as the application's responsibility, not delegated to the database's ACID consistency.
+- [ ] For systems that mix ACID and BASE components, the boundary is explicit: which data lives in which model and why.
+- [ ] Cross-transaction atomicity (sagas, two-phase commit) is recognized as a different problem from in-transaction atomicity. ACID does not solve cross-transaction coordination.
+- [ ] Production incidents that involve data loss or corruption are diagnosed against the specific ACID property that failed — and against the configuration that determined the failure boundary.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Choosing an isolation level for a specific workload | `transaction-isolation` | transaction-isolation owns the I axis in operational depth |
+| Reasoning about replica agreement, availability under partition | `cap-theorem-tradeoffs` | CAP is the distributed-systems frame; this is the single-system frame |
+| Designing the database schema or entity model | `data-modeling` | data-modeling owns design; this owns runtime guarantees |
+| Applying a zero-downtime migration | `database-migration` | database-migration owns migration mechanics |
+| Designing patterns for replicated systems | `replication-patterns` | replication is the operational layer above single-node ACID |
+| Choosing between ACID and BASE for a new system | `cap-theorem-tradeoffs` + this skill | cap-theorem provides the distributed frame; this provides the transactional frame |
+
+## Key Sources
+
+- Härder, T., & Reuter, A. (1983). ["Principles of Transaction-Oriented Database Recovery"](https://dl.acm.org/doi/10.1145/289.291). *ACM Computing Surveys*, 15(4), 287-317. The canonical paper that coined the ACID acronym and consolidated the transaction model.
+- Gray, J. (1981). ["The Transaction Concept: Virtues and Limitations"](https://jimgray.azurewebsites.net/papers/thetransactionconcept.pdf). *VLDB 1981*. The foundational paper on the transaction concept that Härder & Reuter built on.
+- Gray, J., & Reuter, A. (1992). *Transaction Processing: Concepts and Techniques*. Morgan Kaufmann. The canonical textbook on transaction processing; deep treatment of all four ACID properties and their implementation.
+- Kleppmann, M. (2017). *Designing Data-Intensive Applications*. O'Reilly. Chapter 7 (Transactions) provides modern practitioner treatment of ACID, BASE, and the configuration-dependent nature of transactional guarantees.
+- PostgreSQL Global Development Group. ["PostgreSQL Documentation — Transaction Isolation"](https://www.postgresql.org/docs/current/transaction-iso.html). Reference for Postgres's specific implementation of isolation levels and the durability/consistency configuration surface.
+- Pritchett, D. (2008). ["BASE: An Acid Alternative"](https://queue.acm.org/detail.cfm?id=1394128). *ACM Queue*. The canonical practitioner essay defining BASE as the alternative model for high-throughput distributed systems.
+- Bailis, P., & Ghodsi, A. (2013). ["Eventual Consistency Today: Limitations, Extensions, and Beyond"](https://queue.acm.org/detail.cfm?id=2462076). *ACM Queue*. Modern treatment of the consistency models on the BASE side, including extensions to eventual consistency.
+- Brewer, E. (2012). ["CAP Twelve Years Later: How the 'Rules' Have Changed"](https://ieeexplore.ieee.org/document/6133253). *IEEE Computer*, 45(2), 23-29. Brewer's revisit of CAP; useful for grounding the ACID-vs-CAP distinction.
+- Berenson, H., Bernstein, P., Gray, J., Melton, J., O'Neil, E., & O'Neil, P. (1995). ["A Critique of ANSI SQL Isolation Levels"](https://dl.acm.org/doi/10.1145/568271.223785). *SIGMOD 1995*. Foundational paper on the practical issues with isolation-level definitions; required reading for understanding the I axis.