dsh-logicprobe 0.4.0 → 0.5.0

package/skills/logicprobe-datamodel/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: logicprobe-datamodel
+description: "Use when reviewing design documents, architecture specs, technical proposals, schema changes, data contracts, or refactoring plans that make claims about entities, fields, constraints, relationships, data invariants, migration coverage, or before/after data-model equivalence. When the document contains schema changes, data migration logic, or data-behavioral assertions ('all records must have X', 'target count equals source count', 'no orphan rows', 'migration is non-breaking'), escalate into data-model verification — generate and run executable checks for structural consistency, data invariants, migration coverage, copy consistency, and breaking changes before trusting any claim. Also proactively SUGGEST this skill for code-level data/schema behavioral questions."
+---
+
+# Logic Probe Data
+
+Documents are not truth — data models are. Verify every verifiable data claim before accepting or acting on a design.
+
+## Methodology
+
+### Phase 1: Enumerate Data Claims
+
+Read the document fully. Extract every verifiable data-model claim:
+
+- Entity/table/collection names and fields
+- Field types, nullability, defaults, unique constraints
+- Relationships / foreign keys / referential integrity
+- Data invariants ("always", "never", "must", "guaranteed")
+- Migration claims ("rename field", "drop column", "backfill", "non-breaking")
+- Copy/migration mappings ("source.a → target.x")
+
+### Phase 2: Verify Against the Model or Codebase
+
+For each claim, run the relevant verification:
+
+- **Entity/field names**: compare against actual schema, API contract, or code types
+- **Constraints**: check declared `required`, `unique`, `nullable`, `min/max`, `enum`
+- **Relationships**: check target entity/field exists and `onDelete` is coherent
+- **Migration**: build BEFORE/AFTER DataModelV1 and check migration coverage
+
+### Phase 2 Trigger: Escalate to Data Model Verification?
+
+Escalate immediately if the document contains ANY of:
+
+- Schema/migration changes: added/removed/renamed fields, entities, constraints
+- Data invariants: "all rows must", "counts must match", "no orphans", "never null"
+- Copy/migration mappings: source-to-target field maps
+- Before/after data-model equivalence claims: "non-breaking", "behavior preserved"
+- Refactoring that changes field types, nullability, uniqueness, or relationships
+
+## Data Model Verification Pipeline
+
+```text
+Document claims → Extract DataModelV1 → Runtime check:
+  ├── DSH + `logicprobe_datamodel_verify` tool available → build DataModelV1 → call tool → structured report
+  ├── Python available → fill references/data-model-harness.py → run → report
+  └── No Python → Manual Verification Mode (references/data-model-guide.md)
+
+Refactoring variant:
+  Extract BEFORE DataModelV1 + AFTER DataModelV1
+    → Run pipeline on AFTER model (DS/DA checks)
+    → Compare BEFORE vs AFTER (DD1-DD4)
+    → Flag any invariant that held in BEFORE but fails in AFTER
+```
+
+## Checks
+
+### DS — Data structure
+
+| # | Check | Severity if Violated |
+|:--:|-------|:---:|
+| DS1 | Schema well-formedness | Error |
+| DS2 | Required-field completeness | Error/Warning |
+| DS3 | Relationship integrity | Error |
+| DS4 | Type/nullability consistency | Error/Warning |
+
+### DA — Data adversarial probes
+
+| # | Check | Severity if Violated |
+|:--:|-------|:---:|
+| DA1 | Null/empty injection | Error |
+| DA2 | Boundary blast | Warning |
+| DA3 | Uniqueness violation | Error/Warning |
+| DA4 | Referential integrity violation | Warning |
+| DA5 | Migration coverage | Error |
+| DA6 | Copy consistency | Error |
+| DA7 | Rollback/backup symmetry | Warning |
+| DA8 | Idempotent constraints | Error/Warning |
+| DA9 | Data monotonic | Error/Warning |
+| DA10 | Data sequence | Error |
+| DA11 | Data leads-to | Error/Warning |
+| DA12 | Data atomicity | Error/Warning |
+
+### DD — Before/after data regression
+
+| # | Check | Severity if Violated |
+|:--:|-------|:---:|
+| DD1 | Data behavior preservation | Error |
+| DD2 | Data invariant continuity | Error |
+| DD3 | Delta summary | Warning |
+| DD4 | Breaking change regression | Error/Warning |
+
+## Extraction Rule
+
+Before writing any verification code, output a data-model table:
+
+```text
+Entity   | Field      | Type    | Required | Unique | Nullable | Notes
+---------|------------|---------|----------|--------|----------|-------
+User     | id         | uuid    | yes      | yes    | no       | PK
+User     | email      | string  | yes      | yes    | no       |
+Order    | userId     | uuid    | yes      | no     | no       | FK -> User.id
+```
+
+Show this table to the user and ask for confirmation before generating the harness. The #1 failure mode is extracting the wrong data model.
+
+**Exception**: If the runtime reports `logicprobe interaction=auto`, do NOT call `ask_user_question`. Instead: (a) cite evidence for every extracted entity/field/constraint, (b) round-trip the filled model back into a table and compare it with the extraction table, and (c) mark the report `UNCONFIRMED`.
+
+## When NOT to Escalate
+
+Skip data-model verification when:
+
+- The document makes no data-behavioral claims (pure API listings, file paths, numeric constants)
+- The change is purely cosmetic (display names, comments)
+- The data model is trivial (single entity, no constraints, no migration)
+- The claim is purely structural (file paths, type names) — Phase 2 grep verification is sufficient
+
+## Non-Goals
+
+- Not a SQL migration executor (Flyway/Liquibase/Atlas territory)
+- Not a runtime data-quality platform (Great Expectations/Soda territory)
+- Not a general array/object/file-content modeling engine
+- Not a replacement for Atlas/Squawk/Buf/Oasdiff — it is the design-time plan verifier that sits before them

package/skills/logicprobe-datamodel/references/data-model-guide.md

@@ -0,0 +1,62 @@
+# Data Model Manual Verification Mode
+
+Use this when neither the DSH `logicprobe_datamodel_verify` tool nor Python is available. It mirrors the automated DS/DA/DD checks as a structured checklist.
+
+## 1. Extract the DataModelV1 table
+
+For every entity, list fields, types, nullability, required, unique, primary key, and relationships.
+
+```text
+Entity   | Field      | Type    | Required | Unique | Nullable | Notes
+---------|------------|---------|----------|--------|----------|-------
+User     | id         | uuid    | yes      | yes    | no       | PK
+User     | email      | string  | yes      | yes    | no       |
+Order    | userId     | uuid    | yes      | no     | no       | FK -> User.id
+```
+
+## 2. Structural checklist (DS1-DS4)
+
+- [ ] Entity names are unique.
+- [ ] Field names are unique within each entity.
+- [ ] Primary key and unique key fields exist.
+- [ ] Required fields are not nullable.
+- [ ] Relationship targets exist.
+- [ ] `onDelete` values are valid.
+- [ ] `min <= max`, `minLength <= maxLength`.
+
+## 3. Adversarial checklist (DA1-DA7)
+
+- [ ] Null cannot be injected into required fields.
+- [ ] Empty strings are rejected for required string fields.
+- [ ] Boundary values outside min/max are rejected.
+- [ ] Unique/primary key fields are not nullable.
+- [ ] Referenced fields have compatible types.
+- [ ] Every removed/renamed field has a migration mapping.
+- [ ] Every required target field in a copy pair is mapped.
+- [ ] Every copy pair has a matching backup/restore pair.
+- [ ] Every `idempotent-copy` invariant has a matching copy pair.
+- [ ] Every `idempotent-migration` invariant has a matching migration mapping; split/merge/drop are reviewed as non-idempotent.
+- [ ] Monotonic fields only move in the declared direction.
+- [ ] Sequence steps reference existing copy/migration ids.
+- [ ] Leads-to from/to values exist in enum/status fields.
+- [ ] Atomic steps exist, avoid non-atomic transforms, and have backup/restore coverage where applicable.
+
+## 4. Before/after checklist (DD1-DD4)
+
+- [ ] Every BEFORE required field still exists in AFTER or has a migration mapping.
+- [ ] BEFORE data invariants still hold in AFTER.
+- [ ] Added/removed entities, fields, relationships are listed.
+- [ ] No new breaking changes: removed required field, optional→required, nullable→non-null, type narrowing, added unique constraint.
+
+## 5. Output
+
+Append a summary to the plan file:
+
+```markdown
+## Data Model Verification
+
+- **Depth**: LIGHTWEIGHT / STANDARD / ESCALATED
+- **Checks**: [list DS/DA/DD checks performed]
+- **Findings**: [list]
+- **Confirmed**: yes / UNCONFIRMED
+```