diff --git a/README.md b/README.md index 70a0775..dbda4b0 100644 --- a/README.md +++ b/README.md @@ -28,10 +28,10 @@ curl -fsSL https://raw.githubusercontent.com/noormdev/ignatius/main/install.sh | It installs to `/usr/local/bin` when writable, otherwise `$HOME/.local/bin`. Override with `IGNATIUS_INSTALL_DIR`, or pin a version with `IGNATIUS_VERSION=v0.2.0`. Windows users download `ignatius-windows-x64.exe` from the releases page. Prefer to build from source? See [Getting started](docs/guides/getting-started.md). -To author models from Claude Code with guided Q&A, install the `noorm-modeling` skill ([the modeling skill](docs/guides/modeling-skill.md)): +To author models from Claude Code with guided Q&A, install the `ignatius-modeling` skill ([the modeling skill](docs/guides/modeling-skill.md)): ```bash -npx skills add https://github.com/noormdev/ignatius --skill noorm-modeling +npx skills add https://github.com/noormdev/ignatius --skill ignatius-modeling ``` Add `-g` to install it globally for every project instead of just the current one. @@ -62,7 +62,7 @@ Edit any file in the folder and the graph reloads in the browser without a refre | [Process flows](docs/guides/flows.md) | Data flow diagrams: processes, externals, stores, sub-DFDs | | [Validation and findings](docs/guides/validation.md) | The linter, severity tiers, and where findings surface | | [Themes and branding](docs/guides/themes-and-branding.md) | Color palettes, the light/dark toggle, logo and copyright | -| [The modeling skill](docs/guides/modeling-skill.md) | `/noorm-modeling` Q&A authoring in Claude Code | +| [The modeling skill](docs/guides/modeling-skill.md) | `/ignatius-modeling` Q&A authoring in Claude Code | | [Building from source](docs/guides/building-from-source.md) | Build stages, project layout, and tests | The [glossary](docs/glossary.md) defines the shared vocabulary — DG, DD, DFD, data entity, data store, external entity — used across the app, the docs, and the code. diff --git a/docs/design/dfd-nesting-depth.md b/docs/design/dfd-nesting-depth.md index 524af63..a00c783 100644 --- a/docs/design/dfd-nesting-depth.md +++ b/docs/design/dfd-nesting-depth.md @@ -22,7 +22,7 @@ number (e.g. `4.1`) and never receives the `N.` prefix → renders `4.1` instead `5.4.1`. (Even if it were reached, taking only the last segment would collapse `5.4.1` → `5.1`.) The defect is entirely in `deriveLevels`; the parser is correct. -A second, separate gap: `skills/noorm-modeling/references/dfd-authoring.md` Step F8 +A second, separate gap: `skills/ignatius-modeling/references/dfd-authoring.md` Step F8 + the folder-layout sketch show a single sub-DFD level and never state that a child process can itself be decomposed — the skill's implicit one-level cap. @@ -31,7 +31,7 @@ child process can itself be decomposed — the skill's implicit one-level cap. - **Goals** - Dotted process numbers preserve the full ancestor chain at any depth: `N.a`, `N.a.b`, `N.a.b.c`, … - - The `noorm-modeling` skill's `flow` mode authors/organizes nested DFDs down + - The `ignatius-modeling` skill's `flow` mode authors/organizes nested DFDs down arbitrarily many layers (F8 is explicitly recursive). - **Non-goals** - Parser changes — recursion and relative numbering are already correct. diff --git a/docs/design/example-instance-tables.md b/docs/design/example-instance-tables.md index 1a6a7c6..41f382e 100644 --- a/docs/design/example-instance-tables.md +++ b/docs/design/example-instance-tables.md @@ -119,7 +119,7 @@ New rule `entity.example_unknown_column` — Class A, severity `warning`, `liveO E5b runs every time an entity is created. It is not skippable — examples are part of modeling, not a polish step. Verification loop at E8 also checks that the generated examples parse cleanly (no `example_unknown_column` warnings in `ignatius dict` output). -`docs/design/noorm-modeling-skill.md` mermaid updates to show E5b between E5 (columns) and E6 (description). `docs/spec/noorm-modeling-skill.md` gets a change log entry recording the new step. +`docs/design/ignatius-modeling-skill.md` mermaid updates to show E5b between E5 (columns) and E6 (description). `docs/spec/ignatius-modeling-skill.md` gets a change log entry recording the new step. ## Resolved questions diff --git a/docs/design/ignatius-modeling-skill.md b/docs/design/ignatius-modeling-skill.md new file mode 100644 index 0000000..eb1dff5 --- /dev/null +++ b/docs/design/ignatius-modeling-skill.md @@ -0,0 +1,160 @@ +# Ignatius modeling skill + + +## Problem + +Authoring an ignatius entity file today means: + +1. Hand-write the YAML frontmatter without IDE help (no schema, no completion). +2. Remember the IDEF1X classification rules (independent vs dependent vs subtype — including the FK-in-PK = dependent rule that even seasoned users get wrong). +3. Know that group color, sort_key, and theme must live in `groups/*.md` and `ignatius.yml`, not on the entity itself. +4. Run `ignatius dict` afterwards to discover mistakes — by which point the lint surface is reactive, not preventive. + +The result: every new contributor's first entity is a half-broken file that produces lint warnings on first run. Reviewers spend cycles on mechanical issues. The skill is the antidote — a guided authoring loop that produces a properly-formed file the first time and verifies it by invoking the CLI. + + +## Goals / Non-goals + +- **Goals** + - One skill (`/ignatius-modeling`) with two modes selected by a positional arg: + - **`entity`** — author a single entity .md file given an existing `models/` root. + - **`model`** — bootstrap a complete `models/` skeleton (`groups/`, a single `ignatius.yml` carrying optional theme + branding, one or two reference entities). + - The skill knows the IDEF1X rules — it asks the right questions in the right order so the resulting file satisfies the linter on first run. + - After writing, the skill runs `ignatius validate ` and reports any lint findings. If findings appear, the skill prompts the user to fix them iteratively. + - The skill is invoked via the standard Claude Code skill mechanism: `/ignatius-modeling entity` or `/ignatius-modeling model`. Bare `/ignatius-modeling` asks the user to pick. + - Skill output: real file(s) on disk, staged but not committed. + +- **Non-goals** + - The skill is NOT the linter. It depends on the linter (`schema-lint-and-error-ux` spec) to verify output. + - No autonomous bulk-create (skill won't loop through "add 20 entities from a CSV" — single-entity or single-model invocations only). + - No model migration (the older YAML format → current markdown format). `scripts/convert-yaml-to-md.ts` covers that case. + - No reverse-engineering of an existing entity (.md file → form to edit). Could come later. + + +## Sub-modes + + +### `entity` flow + +```mermaid +flowchart TD + Start[User: /ignatius-modeling entity] --> Q1{Models dir specified?} + Q1 -->|no| AskDir[Ask for models/ path] + Q1 -->|yes| Parse[parseModels existing] + AskDir --> Parse + Parse --> Q2[Ask: entity id] + Q2 --> Q3[Ask: group] + Q3 --> Q4[Pick convention
key-inherited or orm-oriented
inherit from model if known] + Q4 --> Q5[Ask: PK columns
guidance per convention] + Q5 --> Q6{Has parent relationships?} + Q6 -->|yes| Q7[Ask: each parent, target + on mapping] + Q6 -->|no| Q8[Skip relationships] + Q7 --> Check{Convention contradicted?} + Check -->|key-inherited + PK omits parent PK| Resolve[Prompt: include parent PK
or switch convention] + Check -->|orm-oriented + FK in PK| Resolve + Check -->|consistent| Q8 + Resolve --> Q5 + Q8 --> Q9[Ask: additional columns] + Q9 --> Q9b[Ask: example rows?
optional — goes in examples: frontmatter] + Q9b --> Q10[Ask: reference table?
default no] + Q10 --> Q11[Ask: optional body description] + Q11 --> Write[Write the .md file] + Write --> Lint[Run ignatius dict + lint] + Lint --> Report{Any findings?} + Report -->|no| Success + Report -->|yes| Loop[Surface findings to user,
offer to edit] + Loop --> Q2 +``` + +Key behavior: the skill uses the user's earlier answers to *prevent* lint violations rather than just catching them. The classification (`Independent`, `Dependent`, `Associative`, `Subtype`, `Classifier`) is **derived by the parser** from PK/FK structure — the skill does not ask. Instead the skill catches **convention contradictions** in the question flow: if the user picked `key-inherited` but declared a PK that omits parent PK columns, or picked `orm-oriented` but put an FK in the PK, the skill prompts to either fix the keys or switch the convention. + +### `model` flow + +```mermaid +flowchart TD + Start[User: /ignatius-modeling model] --> Q1[Ask: target dir
default ./models] + Q1 --> Q2[Ask: model name
for ignatius.yml name + branding title] + Q2 --> Q3[Pick default convention
key-inherited or orm-oriented] + Q3 --> Q4[Ask: theme
default Noorm / custom?] + Q4 --> Q5[Ask: group names + colors
at least 1] + Q5 --> Q6[Optional: bootstrap one
reference entity to demo] + Q6 --> Write[Write groups/*.md,
ignatius.yml with theme + branding,
optionally one entity] + Write --> Lint[Run ignatius dict on new dir] + Lint --> Success +``` + +The skeleton is intentionally minimal — no inflated example data. One group, optionally one entity, ready to grow. The default convention is recorded as a comment in `ignatius.yml` so subsequent `entity` invocations against this root inherit it. + + +## Invocation + +- Skill file lives in this repo so it ships with the project. Path: `skills/ignatius-modeling/SKILL.md` (project-scoped skill). +- Name: `/ignatius-modeling`. One skill, one file. Mode selected by positional arg: `entity` or `model`. +- Bare `/ignatius-modeling` (no arg) prompts the user to pick which mode. Unknown args fall to the same prompt. +- Invokable from anywhere; if not inside an ignatius `models/`-bearing project the skill asks for paths. + + +## Knowledge encoded in the skill + +The single `SKILL.md` must encode: + +- The exact required + optional fields for an entity .md file (id, group, pk, columns, relationships, alternateKeys, reference, body). **No `classification`, no per-edge `identifying`** — both are derived by the parser. +- The **authoring convention axis** (`key-inherited` vs `orm-oriented`) and how key placement differs: + - `key-inherited`: parent PK propagates into child composite PK; FK columns live in the child PK. + - `orm-oriented`: each entity has a single surrogate `id` PK; FK columns sit outside the PK as plain columns. +- The convention-contradiction detection rules: + - `key-inherited` + PK that omits parent PK columns → prompt to include them or switch convention. + - `orm-oriented` + FK column in the PK → prompt to drop it or switch convention. +- The IDEF1X *intuition* behind the conventions (so the user understands what derivation will produce), but **never as a question the user has to answer**. Classification follows from key shape. +- The `groups/*.md` schema (label, color, optional sort_key, optional desc). +- The `ignatius.yml` schema (`name`, `version`, `description`, `updated`, `theme:`, `branding:` blocks — single config file per `docs/spec/ignatius-project-config.md`). +- Pointers to the linter rule catalog so the skill's questions map 1:1 with what the linter would flag. + +These are kept in sync with the canonical sources — `docs/spec/schema-lint-and-error-ux.md`, `docs/spec/derive-classification.md`, `docs/spec/ignatius-project-config.md`, and `docs/design/markdown-driven-erd.md`. If the linter rules change, the skill author updates the skill: explicit, not automatic. + +The citation lives HERE, not in the skill. `npx skills add … --skill ignatius-modeling` copies only `skills/ignatius-modeling/` into the user's `.claude/skills/`, so a repo-relative path written into `SKILL.md` or any `references/*.md` is a dead link on every machine but this one — and Claude will try to Read it. Nothing shipped in the skill may cite `docs/`, `src/`, `spec/`, or any other repo path. A pointer with genuine user value goes in as a full `https://github.com/noormdev/ignatius/blob/main/…` URL; a maintainer-only pointer stays in this document. + + +## Verification loop + +After writing files, the skill runs `ignatius validate ` (the validate-only quality gate — no HTML output) and parses the CLI's stderr lint output (the format defined by `schema-lint-and-error-ux`). For each finding: + +- The skill reports the category + message + fix hint to the user. +- The skill offers to revise: "Update the file?" — if yes, the skill walks the relevant question subset again with the original answers prefilled, writes the file, re-runs. +- Loop bounded to 5 attempts (defensive against infinite cycles from misbehaving CLI). + +The verification step depends on the linter's structured stderr — `src/validate.ts:formatFindingsForStderr` is live and emits ` ` one line per finding, called from `src/cli.ts` after `parseModels` + `validateModel`. The skill parses that format directly; no soft-verify gate remains. + + +## Open questions + +- **Skill auto-stage?** Should the skill `git add` the new file(s)? Likely no — leave staging to the user. They might want to iterate before committing. +- **Body markdown content** — should the skill ask for a short description or leave the body blank? Probably ask for an optional one-sentence summary; longer prose is better written outside a Q&A flow. + + +## Approaches considered and rejected + +| Rejected | Why | +|----------|-----| +| Two separate skills (`/new-entity` + `/new-model`) | User picked "separate sub-modes" — one skill, two args — in the original clarify round. Splitting into two skill files contradicts that selection and doubles the surface for no benefit. | +| Hand-rolled CLI subcommand (`ignatius new entity`) | Skills are the right surface — interactive, in-IDE, in the same loop as everything else Claude Code touches. CLI sub-command duplicates that surface. | +| Skill that writes through a templating library (Mustache, EJS) | Overkill. Skills are markdown + LLM judgment; templates would add a dep without buying much. | +| Skill that bypasses the linter and trusts its own checks | Would diverge over time. Skill DEPENDS on the linter; doesn't reimplement it. | +| Skill that doesn't verify (just writes the file) | Fails the goal — the whole point is "lint-clean on first run". Verify is non-optional. | + + +## Change log + + +### 2026-06-17 — Folder model migration (#16): groups/ path and entity location + +**What changed:** All references to the group definition directory updated from `_groups/` to `groups/`. The model bootstrap and entity authoring steps now write group definitions under `groups/` at the model root; entity files go under `data//`. + +**Superseded:** Group definitions were described as living in `_groups/*.md`. Entity files were globbed from the model root without a `data/` container. + + +### 2026-08-11 — Rename skill to ignatius-modeling + +**What changed:** The skill renamed `noorm-modeling` → `ignatius-modeling`; this design doc moved from `docs/design/noorm-modeling-skill.md`. + +**Why:** The skill ships with and authors ignatius models; the name now matches the product instead of the noorm umbrella. diff --git a/docs/design/noorm-flow-discovery.md b/docs/design/noorm-flow-discovery.md index 81b06c7..34fd893 100644 --- a/docs/design/noorm-flow-discovery.md +++ b/docs/design/noorm-flow-discovery.md @@ -3,7 +3,7 @@ ## Problem -The `noorm-modeling` skill authors ERD entities (`entity` mode) and bootstraps models (`model` mode). It has **no mode for authoring SSADM data flow diagrams** — the flows feature ships parsing, validation, and an in-app viewer, but a user writes flow markdown by hand against `docs/spec/process-flows.md`. Two distinct gaps: +The `ignatius-modeling` skill authors ERD entities (`entity` mode) and bootstraps models (`model` mode). It has **no mode for authoring SSADM data flow diagrams** — the flows feature ships parsing, validation, and an in-app viewer, but a user writes flow markdown by hand against `docs/spec/process-flows.md`. Two distinct gaps: 1. **No structured flow-authoring path.** A user who already knows their processes still hand-writes `process:`/`inputs:`/`outputs:`/`examples:` frontmatter, the `externals/` and `stores/` folder layout at the model root, and the `db:`/`kind:` store taxonomy — with no guide and no first-run verification. @@ -146,7 +146,7 @@ Lives in `references/reverse-engineering.md`, routed to from `discover` when a s | # | Approach | Pros | Cons | |---|----------|------|------| -| A | Two new modes on `noorm-modeling` (`flow` + `discover`), reusing the SKILL.md + references scaffold | Single skill knows both ERD and flows, so `db:` resolution and discovery's entity-derivation stay coherent; matches existing two-mode structure | SKILL.md grows; four modes to route | +| A | Two new modes on `ignatius-modeling` (`flow` + `discover`), reusing the SKILL.md + references scaffold | Single skill knows both ERD and flows, so `db:` resolution and discovery's entity-derivation stay coherent; matches existing two-mode structure | SKILL.md grows; four modes to route | | B | A separate `noorm-flows` skill | Smaller per-skill surface | Splits the model knowledge in two; discovery (which emits entities) would straddle both skills; `db:` store resolution needs the ERD anyway | | C | New validator rules to enforce examples + context richness | Code-guaranteed | User explicitly rejected: LLMs remember; "be and maybe be" not a code problem; blocks half-authored flows from validating | | D | Bake the store-kind taxonomy into the validator as an enum | Standardized in code | User chose skill-side menu; keeps the kind list a suggestion, not a hard contract | @@ -156,7 +156,7 @@ Lives in `references/reverse-engineering.md`, routed to from `discover` when a s **Approach A.** Discovery's defining move — deriving entities from processes (gate 4) and writing the ERD before the DFD — only works if one skill owns both entity and flow authoring. Splitting (B) would force discovery to straddle two skills. Code-side enforcement (C, D) was settled against with the user: the method enforces examples and richness; the existing `flow-validate.ts` rules are the backstop, unchanged. -Evidence: existing skill scaffold (`skills/noorm-modeling/SKILL.md` + `references/*.md`) already carries two modes and the core rules `flow` mode inherits verbatim (positive form, act-don't-suggest, infer-before-asking, derive-never-ask). The logical apparatus is modeled on `~/.claude/commands/pressure-test.md` lines 73–102 (three laws, four causes, sufficient reason) — translated to a generative posture, not cloned. Canonical rules and the existing ignatius adoption decisions live in `docs/research/ssadm-dfd-rules.md`. +Evidence: existing skill scaffold (`skills/ignatius-modeling/SKILL.md` + `references/*.md`) already carries two modes and the core rules `flow` mode inherits verbatim (positive form, act-don't-suggest, infer-before-asking, derive-never-ask). The logical apparatus is modeled on `~/.claude/commands/pressure-test.md` lines 73–102 (three laws, four causes, sufficient reason) — translated to a generative posture, not cloned. Canonical rules and the existing ignatius adoption decisions live in `docs/research/ssadm-dfd-rules.md`. ## Resolved decisions diff --git a/docs/design/noorm-modeling-skill.md b/docs/design/noorm-modeling-skill.md index 97c311d..fa94ce5 100644 --- a/docs/design/noorm-modeling-skill.md +++ b/docs/design/noorm-modeling-skill.md @@ -1,153 +1,12 @@ -# Noorm modeling skill +# Noorm modeling skill (moved) -## Problem - -Authoring an ignatius entity file today means: - -1. Hand-write the YAML frontmatter without IDE help (no schema, no completion). -2. Remember the IDEF1X classification rules (independent vs dependent vs subtype — including the FK-in-PK = dependent rule that even seasoned users get wrong). -3. Know that group color, sort_key, and theme must live in `groups/*.md` and `ignatius.yml`, not on the entity itself. -4. Run `ignatius dict` afterwards to discover mistakes — by which point the lint surface is reactive, not preventive. - -The result: every new contributor's first entity is a half-broken file that produces lint warnings on first run. Reviewers spend cycles on mechanical issues. The skill is the antidote — a guided authoring loop that produces a properly-formed file the first time and verifies it by invoking the CLI. - - -## Goals / Non-goals - -- **Goals** - - One skill (`/noorm-modeling`) with two modes selected by a positional arg: - - **`entity`** — author a single entity .md file given an existing `models/` root. - - **`model`** — bootstrap a complete `models/` skeleton (`groups/`, a single `ignatius.yml` carrying optional theme + branding, one or two reference entities). - - The skill knows the IDEF1X rules — it asks the right questions in the right order so the resulting file satisfies the linter on first run. - - After writing, the skill runs `ignatius validate ` and reports any lint findings. If findings appear, the skill prompts the user to fix them iteratively. - - The skill is invoked via the standard Claude Code skill mechanism: `/noorm-modeling entity` or `/noorm-modeling model`. Bare `/noorm-modeling` asks the user to pick. - - Skill output: real file(s) on disk, staged but not committed. - -- **Non-goals** - - The skill is NOT the linter. It depends on the linter (`schema-lint-and-error-ux` spec) to verify output. - - No autonomous bulk-create (skill won't loop through "add 20 entities from a CSV" — single-entity or single-model invocations only). - - No model migration (the older YAML format → current markdown format). `scripts/convert-yaml-to-md.ts` covers that case. - - No reverse-engineering of an existing entity (.md file → form to edit). Could come later. - - -## Sub-modes - - -### `entity` flow - -```mermaid -flowchart TD - Start[User: /noorm-modeling entity] --> Q1{Models dir specified?} - Q1 -->|no| AskDir[Ask for models/ path] - Q1 -->|yes| Parse[parseModels existing] - AskDir --> Parse - Parse --> Q2[Ask: entity id] - Q2 --> Q3[Ask: group] - Q3 --> Q4[Pick convention
key-inherited or orm-oriented
inherit from model if known] - Q4 --> Q5[Ask: PK columns
guidance per convention] - Q5 --> Q6{Has parent relationships?} - Q6 -->|yes| Q7[Ask: each parent, target + on mapping] - Q6 -->|no| Q8[Skip relationships] - Q7 --> Check{Convention contradicted?} - Check -->|key-inherited + PK omits parent PK| Resolve[Prompt: include parent PK
or switch convention] - Check -->|orm-oriented + FK in PK| Resolve - Check -->|consistent| Q8 - Resolve --> Q5 - Q8 --> Q9[Ask: additional columns] - Q9 --> Q9b[Ask: example rows?
optional — goes in examples: frontmatter] - Q9b --> Q10[Ask: reference table?
default no] - Q10 --> Q11[Ask: optional body description] - Q11 --> Write[Write the .md file] - Write --> Lint[Run ignatius dict + lint] - Lint --> Report{Any findings?} - Report -->|no| Success - Report -->|yes| Loop[Surface findings to user,
offer to edit] - Loop --> Q2 -``` - -Key behavior: the skill uses the user's earlier answers to *prevent* lint violations rather than just catching them. The classification (`Independent`, `Dependent`, `Associative`, `Subtype`, `Classifier`) is **derived by the parser** from PK/FK structure — the skill does not ask. Instead the skill catches **convention contradictions** in the question flow: if the user picked `key-inherited` but declared a PK that omits parent PK columns, or picked `orm-oriented` but put an FK in the PK, the skill prompts to either fix the keys or switch the convention. - -### `model` flow - -```mermaid -flowchart TD - Start[User: /noorm-modeling model] --> Q1[Ask: target dir
default ./models] - Q1 --> Q2[Ask: model name
for ignatius.yml name + branding title] - Q2 --> Q3[Pick default convention
key-inherited or orm-oriented] - Q3 --> Q4[Ask: theme
default Noorm / custom?] - Q4 --> Q5[Ask: group names + colors
at least 1] - Q5 --> Q6[Optional: bootstrap one
reference entity to demo] - Q6 --> Write[Write groups/*.md,
ignatius.yml with theme + branding,
optionally one entity] - Write --> Lint[Run ignatius dict on new dir] - Lint --> Success -``` - -The skeleton is intentionally minimal — no inflated example data. One group, optionally one entity, ready to grow. The default convention is recorded as a comment in `ignatius.yml` so subsequent `entity` invocations against this root inherit it. - - -## Invocation - -- Skill file lives in this repo so it ships with the project. Path: `skills/noorm-modeling/SKILL.md` (project-scoped skill). -- Name: `/noorm-modeling`. One skill, one file. Mode selected by positional arg: `entity` or `model`. -- Bare `/noorm-modeling` (no arg) prompts the user to pick which mode. Unknown args fall to the same prompt. -- Invokable from anywhere; if not inside an ignatius `models/`-bearing project the skill asks for paths. - - -## Knowledge encoded in the skill - -The single `SKILL.md` must encode: - -- The exact required + optional fields for an entity .md file (id, group, pk, columns, relationships, alternateKeys, reference, body). **No `classification`, no per-edge `identifying`** — both are derived by the parser. -- The **authoring convention axis** (`key-inherited` vs `orm-oriented`) and how key placement differs: - - `key-inherited`: parent PK propagates into child composite PK; FK columns live in the child PK. - - `orm-oriented`: each entity has a single surrogate `id` PK; FK columns sit outside the PK as plain columns. -- The convention-contradiction detection rules: - - `key-inherited` + PK that omits parent PK columns → prompt to include them or switch convention. - - `orm-oriented` + FK column in the PK → prompt to drop it or switch convention. -- The IDEF1X *intuition* behind the conventions (so the user understands what derivation will produce), but **never as a question the user has to answer**. Classification follows from key shape. -- The `groups/*.md` schema (label, color, optional sort_key, optional desc). -- The `ignatius.yml` schema (`name`, `version`, `description`, `updated`, `theme:`, `branding:` blocks — single config file per `docs/spec/ignatius-project-config.md`). -- Pointers to the linter rule catalog so the skill's questions map 1:1 with what the linter would flag. - -These are kept in sync with the canonical sources — `docs/spec/schema-lint-and-error-ux.md`, `docs/spec/derive-classification.md`, `docs/spec/ignatius-project-config.md`, and `docs/design/markdown-driven-erd.md`. If the linter rules change, the skill author updates the skill: explicit, not automatic. - -The citation lives HERE, not in the skill. `npx skills add … --skill noorm-modeling` copies only `skills/noorm-modeling/` into the user's `.claude/skills/`, so a repo-relative path written into `SKILL.md` or any `references/*.md` is a dead link on every machine but this one — and Claude will try to Read it. Nothing shipped in the skill may cite `docs/`, `src/`, `spec/`, or any other repo path. A pointer with genuine user value goes in as a full `https://github.com/noormdev/ignatius/blob/main/…` URL; a maintainer-only pointer stays in this document. - - -## Verification loop - -After writing files, the skill runs `ignatius validate ` (the validate-only quality gate — no HTML output) and parses the CLI's stderr lint output (the format defined by `schema-lint-and-error-ux`). For each finding: - -- The skill reports the category + message + fix hint to the user. -- The skill offers to revise: "Update the file?" — if yes, the skill walks the relevant question subset again with the original answers prefilled, writes the file, re-runs. -- Loop bounded to 5 attempts (defensive against infinite cycles from misbehaving CLI). - -The verification step depends on the linter's structured stderr — `src/validate.ts:formatFindingsForStderr` is live and emits ` ` one line per finding, called from `src/cli.ts` after `parseModels` + `validateModel`. The skill parses that format directly; no soft-verify gate remains. - - -## Open questions - -- **Skill auto-stage?** Should the skill `git add` the new file(s)? Likely no — leave staging to the user. They might want to iterate before committing. -- **Body markdown content** — should the skill ask for a short description or leave the body blank? Probably ask for an optional one-sentence summary; longer prose is better written outside a Q&A flow. - - -## Approaches considered and rejected - -| Rejected | Why | -|----------|-----| -| Two separate skills (`/new-entity` + `/new-model`) | User picked "separate sub-modes" — one skill, two args — in the original clarify round. Splitting into two skill files contradicts that selection and doubles the surface for no benefit. | -| Hand-rolled CLI subcommand (`ignatius new entity`) | Skills are the right surface — interactive, in-IDE, in the same loop as everything else Claude Code touches. CLI sub-command duplicates that surface. | -| Skill that writes through a templating library (Mustache, EJS) | Overkill. Skills are markdown + LLM judgment; templates would add a dep without buying much. | -| Skill that bypasses the linter and trusts its own checks | Would diverge over time. Skill DEPENDS on the linter; doesn't reimplement it. | -| Skill that doesn't verify (just writes the file) | Fails the goal — the whole point is "lint-clean on first run". Verify is non-optional. | +Renamed. Current design doc: [`ignatius-modeling-skill.md`](./ignatius-modeling-skill.md). ## Change log -### 2026-06-17 — Folder model migration (#16): groups/ path and entity location - -**What changed:** All references to the group definition directory updated from `_groups/` to `groups/`. The model bootstrap and entity authoring steps now write group definitions under `groups/` at the model root; entity files go under `data//`. +### 2026-08-11 — Renamed to ignatius-modeling-skill.md -**Superseded:** Group definitions were described as living in `_groups/*.md`. Entity files were globbed from the model root without a `data/` container. +**What changed:** Design doc moved to `docs/design/ignatius-modeling-skill.md`; the skill itself renamed `noorm-modeling` → `ignatius-modeling`. This stub stays one commit so grep finds both names, then gets deleted. diff --git a/docs/design/process-flows.md b/docs/design/process-flows.md index 35547e5..645a638 100644 --- a/docs/design/process-flows.md +++ b/docs/design/process-flows.md @@ -205,7 +205,7 @@ Genuinely still open: - **Queue/message payload validation.** v1 treats every non-`db:` flow as an opaque label. A `queue:` message often has a known payload shape worth checking — validating it against a declared schema is a separate, larger feature than `stores/` descriptions. Out of scope for v1; decide if/when it's wanted. - **Numbering gaps.** Sibling-local uniqueness is enforced (`flow.duplicate_number`); whether a gap (`1, 2, 4`) should also warn is undecided. Left silent for now. - **Usage index (deferred).** A derived back-reference — for any store or entity, every flow/process that reads or writes it (the reverse of the demand list). Filed as a `kind: plan` follow-up (`.claude/project/followups/usage-index-back-reference.md`); deliberately not specced so it isn't half-built as a side effect of `stores/`. -- **Surfaces to update on landing.** New signals domain, a `Feature ↔ documentation ↔ skill map` row, and likely a `noorm-modeling` skill mode for authoring flows. +- **Surfaces to update on landing.** New signals domain, a `Feature ↔ documentation ↔ skill map` row, and likely a `ignatius-modeling` skill mode for authoring flows. ## Change log diff --git a/docs/guides/flows.md b/docs/guides/flows.md index 4a429d5..8420179 100644 --- a/docs/guides/flows.md +++ b/docs/guides/flows.md @@ -145,4 +145,4 @@ Hovering a data flow edge that carries data (the arrow between two nodes) reveal ## Authoring with the skill -The [`noorm-modeling` skill](modeling-skill.md) has two modes for flows: `/noorm-modeling flow` walks you through authoring a diagram step by step when you already know your processes, and `/noorm-modeling discover` interviews you about how the business runs and generates both the entities and the flows, with examples. Both verify their output with `ignatius validate`. +The [`ignatius-modeling` skill](modeling-skill.md) has two modes for flows: `/ignatius-modeling flow` walks you through authoring a diagram step by step when you already know your processes, and `/ignatius-modeling discover` interviews you about how the business runs and generates both the entities and the flows, with examples. Both verify their output with `ignatius validate`. diff --git a/docs/guides/getting-started.md b/docs/guides/getting-started.md index 4492785..1e5d0b2 100644 --- a/docs/guides/getting-started.md +++ b/docs/guides/getting-started.md @@ -90,4 +90,4 @@ If the path contains multiple model folders, ignatius lists them and prompts you - [What gets derived](derivation.md) — cardinality, classification, and subtype clusters come from the structure, not from labels you set. - [Process flows](flows.md) — add data flow diagrams that show how processes move the data. - [Commands](commands.md) — `serve`, `export`, and `validate` in full. -- [Authoring with the modeling skill](modeling-skill.md) — let `/noorm-modeling` write entity and flow files for you. +- [Authoring with the modeling skill](modeling-skill.md) — let `/ignatius-modeling` write entity and flow files for you. diff --git a/docs/guides/modeling-skill.md b/docs/guides/modeling-skill.md index c33ecb6..2b8a693 100644 --- a/docs/guides/modeling-skill.md +++ b/docs/guides/modeling-skill.md @@ -1,7 +1,7 @@ # The modeling skill -`/noorm-modeling` is a Claude Code skill that guides you through authoring a model via Q&A — one entity, a data flow diagram, a fresh model skeleton, or a full Socratic discovery session that works the model out from how your business runs — then verifies the result with `ignatius validate`. +`/ignatius-modeling` is a Claude Code skill that guides you through authoring a model via Q&A — one entity, a data flow diagram, a fresh model skeleton, or a full Socratic discovery session that works the model out from how your business runs — then verifies the result with `ignatius validate`. **Prerequisites:** Claude Code with skill support, and the `ignatius` binary on your `$PATH` or built locally (`bun run build:cli` produces `dist/ignatius`). @@ -12,10 +12,10 @@ Install the skill into the current project with the [`skills`](https://www.npmjs.com/package/skills) CLI: ```bash -npx skills add https://github.com/noormdev/ignatius --skill noorm-modeling +npx skills add https://github.com/noormdev/ignatius --skill ignatius-modeling ``` -This adds `noorm-modeling` to the project's `.claude/skills/`. Add `-g` to install it globally so it is available in every project on the machine. Reload skills in Claude Code and `/noorm-modeling` becomes available. +This adds `ignatius-modeling` to the project's `.claude/skills/`. Add `-g` to install it globally so it is available in every project on the machine. Reload skills in Claude Code and `/ignatius-modeling` becomes available. ## Modes @@ -23,24 +23,24 @@ This adds `noorm-modeling` to the project's `.claude/skills/`. Add `-g` to insta | Invocation | What it does | |---|---| -| `/noorm-modeling entity` | Interactive Q&A to author one entity `.md` file | -| `/noorm-modeling model` | Bootstrap a new model skeleton (`ignatius.yml`, group files, directories) | -| `/noorm-modeling flow` | Interactive Q&A to author a [data flow diagram](flows.md) — for when you already know your processes | -| `/noorm-modeling discover` | Socratic interview that works out the model from how your business runs, generating both entities and flows | -| `/noorm-modeling` (no arg) | Prompts you to choose a mode | +| `/ignatius-modeling entity` | Interactive Q&A to author one entity `.md` file | +| `/ignatius-modeling model` | Bootstrap a new model skeleton (`ignatius.yml`, group files, directories) | +| `/ignatius-modeling flow` | Interactive Q&A to author a [data flow diagram](flows.md) — for when you already know your processes | +| `/ignatius-modeling discover` | Socratic interview that works out the model from how your business runs, generating both entities and flows | +| `/ignatius-modeling` (no arg) | Prompts you to choose a mode | ```bash # Add a new entity to an existing model -/noorm-modeling entity +/ignatius-modeling entity # Start a new model from scratch -/noorm-modeling model +/ignatius-modeling model # Author a DFD for processes you already know -/noorm-modeling flow +/ignatius-modeling flow # Work out the model from a business description -/noorm-modeling discover +/ignatius-modeling discover ``` diff --git a/docs/spec/cli-and-outputs.md b/docs/spec/cli-and-outputs.md index 029e270..3581c13 100644 --- a/docs/spec/cli-and-outputs.md +++ b/docs/spec/cli-and-outputs.md @@ -79,7 +79,7 @@ The graph output is the same React app, with the model baked in instead of fetch **What changed:** New `validate` subcommand: parses + validates a model and prints findings to stderr (same ` ` format as `dict`/`graph`) plus a one-line stdout summary, writing no HTML. No `-o` flag. Exit code matches the other commands (1 on global errors, 0 otherwise). Added to the success criteria and approach. -**Why:** A validate-only path is a fast quality gate for authoring loops (no bundle, no file written) — adopted by the noorm-modeling skill's verification loop in place of generating a throwaway dict HTML purely to lint. +**Why:** A validate-only path is a fast quality gate for authoring loops (no bundle, no file written) — adopted by the ignatius-modeling skill's verification loop in place of generating a throwaway dict HTML purely to lint. ### 2026-05-28 — Rename CLI from `derek` to `ignatius` diff --git a/docs/spec/derive-classification.md b/docs/spec/derive-classification.md index 1d46233..cc65a94 100644 --- a/docs/spec/derive-classification.md +++ b/docs/spec/derive-classification.md @@ -62,7 +62,7 @@ Built across 2 iterations of /subagent-implementation (inline brief, no prior sp - The compiled binary embeds a parser snapshot; stripping the fields broke the old binary until rebuilt. Confirms the binary must be rebuilt whenever parser-visible model shape changes. **Deferred items still open (disposition at finalize):** -- `docs/spec/noorm-modeling-skill.md`, `docs/spec/schema-lint-and-error-ux.md`, and followup `ignatius-authoring-skill` reference a hand-authored `classification` that no longer exists — reconcile needed. +- `docs/spec/ignatius-modeling-skill.md`, `docs/spec/schema-lint-and-error-ux.md`, and followup `ignatius-authoring-skill` reference a hand-authored `classification` that no longer exists — reconcile needed. - 6 pre-existing `tsc --noEmit` errors in `src/parse.ts` (predate this work). diff --git a/docs/spec/dfd-nesting-depth.md b/docs/spec/dfd-nesting-depth.md index 1a13091..507a03f 100644 --- a/docs/spec/dfd-nesting-depth.md +++ b/docs/spec/dfd-nesting-depth.md @@ -4,7 +4,7 @@ DFD dotted process numbers preserve the full ancestor chain at any nesting depth (`N.a`, `N.a.b`, `N.a.b.c`, …) instead of dropping ancestor segments beyond ~2 -levels (the user-observed `5.4.1` → `4.1` bug). The `noorm-modeling` skill's +levels (the user-observed `5.4.1` → `4.1` bug). The `ignatius-modeling` skill's `flow` mode authors nested DFDs down arbitrarily many layers. Implements issue #15. ## Non-goals @@ -29,7 +29,7 @@ number. - [ ] The existing `test/fixtures/flows-leveling/` fixture (auth → Authenticate → Login → VerifyToken/CreateSession, 3 process levels deep) is used by a new check in `test/checks/` that parses it via `parseFlows` and asserts the full-depth dotted numbers: `Authenticate` = `1.1`, `Login` = `1.1.1`, `VerifyToken` = `1.1.1.1`, `CreateSession` = `1.1.1.2` (auth is the sole top-level diagram → L1 process `1`). The test must FAIL against the pre-fix `renumberLeaf` — which currently yields `Login = 1.1` (colliding with `Authenticate`), `VerifyToken = 1.1.1`, `CreateSession = 1.1.2`, all missing the ancestor prefix. - [ ] No regression: `test/checks/test-leveling.ts`, `test/checks/test-flow-leveling.ts`, and `test/checks/test-parse-flows.ts` still pass (existing 1–2 level dotted numbers unchanged). - [ ] The `test/fixtures/flows-leveling/` fixture is made servable (minimal `ignatius.yml` + a minimal `Party` entity so its `db:Party` endpoints resolve cleanly), and a `test/visual/` screenshot script serves it and captures the DD process list (and/or the drilled Login sub-DFD) showing the full-depth numbers `1.1`, `1.1.1`, `1.1.1.1`, `1.1.1.2`. Additions live entirely inside the fixture dir; `parseFlows`-based checks (`test-deep-nesting.ts`, `test-flow-leveling.ts`) are unaffected. -- [ ] `skills/noorm-modeling/references/dfd-authoring.md` Step F8 is rewritten so decomposition is explicitly recursive — a child process may itself become a sub-DFD parent, down as many layers as warranted — and the folder-layout sketch shows a second nesting level. Any other skill surface that caps depth (e.g. `flow-templates.md`) is reconciled. +- [ ] `skills/ignatius-modeling/references/dfd-authoring.md` Step F8 is rewritten so decomposition is explicitly recursive — a child process may itself become a sub-DFD parent, down as many layers as warranted — and the folder-layout sketch shows a second nesting level. Any other skill surface that caps depth (e.g. `flow-templates.md`) is reconciled. - [ ] `bun run test` passes (all `test/checks/*.ts`, exit 0). `bun run build:cli` succeeds. - [ ] Touched source files introduce **zero** new `tsc --noEmit` errors vs. the baseline. - [ ] CLAUDE.md feature map + `docs/guides/flows.md` reflect arbitrary nesting depth (the "Sub-DFDs" section already says "recurses as deep as it needs to" — confirm it's accurate and add the dotted-number depth note if missing). @@ -40,7 +40,7 @@ number. |---|------------|-------------|-------|------------|----------| | 1 | Fix `renumberLeaf` (recurse + full prefix) + failing check on the existing deep fixture | `src/flows/flow-derive-levels.ts`, `test/checks/test-deep-nesting.ts` (new, uses existing `test/fixtures/flows-leveling/`) | atomic-implementer (feature) | 2 | `Authenticate=1.1`, `Login=1.1.1`, `VerifyToken=1.1.1.1`, `CreateSession=1.1.1.2`; no regression | | 2 | Make `flows-leveling` servable + screenshot rendered deep numbers | `test/fixtures/flows-leveling/ignatius.yml` (new), minimal `Party` entity (new), `test/visual/test-deep-nesting.ts` (new) | atomic-implementer (feature) | 3-4 | served deep fixture shows `1.1.1.1` in DD process list / drilled sub-DFD | -| 3 | Skill: recursive F8 + folder-layout depth; docs reconciliation | `skills/noorm-modeling/references/dfd-authoring.md`, `CLAUDE.md`, `docs/guides/flows.md` | atomic-implementer (surgical) | 2-3 | F8 explicitly recursive; layout shows ≥2 nesting levels; guide/map accurate | +| 3 | Skill: recursive F8 + folder-layout depth; docs reconciliation | `skills/ignatius-modeling/references/dfd-authoring.md`, `CLAUDE.md`, `docs/guides/flows.md` | atomic-implementer (surgical) | 2-3 | F8 explicitly recursive; layout shows ≥2 nesting levels; guide/map accurate | ## Risks diff --git a/docs/spec/example-instance-tables.md b/docs/spec/example-instance-tables.md index c921f1f..31d033e 100644 --- a/docs/spec/example-instance-tables.md +++ b/docs/spec/example-instance-tables.md @@ -30,10 +30,10 @@ Authors attach `examples:` to entity frontmatter as an array of row objects. Exa - [ ] Tapping any node in the graph viewer opens an entity-detail modal containing id, classification badge, group color, body HTML, columns table, and the examples accordion at the bottom. - [ ] ESC or backdrop click closes the modal; hash-router entity selection persists across modal open/close. - [ ] Live-mode graph viewer shows `entity.example_unknown_column` warnings in the findings panel; static mode does not. -- [ ] `skills/noorm-modeling/references/entity-flow.md` lists a new step **E7b — Examples** between E7 (Columns) and E8 (Reference table), with instructions to always generate 2–3 example rows during the entity flow. (The actual entity-flow ordering as of this spec is E0…E10 with E5=Relationships, E6=Alternate keys, E7=Columns, E8=Reference table flag, E9=Business context, E10=Write file. Examples logically belong after columns are defined so the row shape exists, but before the reference-flag / business-context steps so example data can inform those.) -- [ ] `skills/noorm-modeling/SKILL.md` references the new step where appropriate (e.g. in the high-level outline if one exists). -- [ ] `docs/design/noorm-modeling-skill.md` mermaid reflects E7b in the entity flow if it currently diagrams E-steps. -- [ ] `docs/spec/noorm-modeling-skill.md` has a `## Change log` entry recording the E7b amendment. +- [ ] `skills/ignatius-modeling/references/entity-flow.md` lists a new step **E7b — Examples** between E7 (Columns) and E8 (Reference table), with instructions to always generate 2–3 example rows during the entity flow. (The actual entity-flow ordering as of this spec is E0…E10 with E5=Relationships, E6=Alternate keys, E7=Columns, E8=Reference table flag, E9=Business context, E10=Write file. Examples logically belong after columns are defined so the row shape exists, but before the reference-flag / business-context steps so example data can inform those.) +- [ ] `skills/ignatius-modeling/SKILL.md` references the new step where appropriate (e.g. in the high-level outline if one exists). +- [ ] `docs/design/ignatius-modeling-skill.md` mermaid reflects E7b in the entity flow if it currently diagrams E-steps. +- [ ] `docs/spec/ignatius-modeling-skill.md` has a `## Change log` entry recording the E7b amendment. - [ ] All 24 entity files under `models/key-inherited/` have `examples:` blocks with at least 2 rows each. Existing clean-baseline tests still report 0 findings. - [ ] `models/broken-demo/` amends an **existing** entity (not a new one — keeps the pin count deterministic) to add an `examples:` block containing one row with a key outside `columns ∪ pk`. The broken-pin test (`test/checks/test-validate-entity.ts`) sees exactly +1 entity error in live mode; CLI stderr counts (`test/checks/test-validate-refs.ts` or similar) are unchanged. - [ ] Playwright visual checks for the dict accordion and the graph modal exist in `test/visual/`. These are manual-only — not wired into `bun run test` or CI. @@ -76,7 +76,7 @@ Live-only validation: | 2 | Validator rule + `liveOnly` filter | `src/validate.ts`; `test/checks/test-validate-examples.ts` | atomic-builder | ~2 | New check passes (asserts firing + non-firing cases + `formatFindingsForStderr` drops live-only); existing validator checks unchanged | | 3 | Dict accordion render | `src/generators/dict.ts`; possibly `src/styles.css` if dict styles inline; `test/visual/screenshot-dict-examples.ts` | atomic-builder | ~3 | Playwright screenshot shows accordion under body; static-mode findings banner omits live-only warnings | | 4 | Graph entity-detail modal + examples accordion | `src/App.tsx`; `src/styles.css`; `test/visual/screenshot-entity-modal.ts` | atomic-builder | ~3 | Playwright screenshot shows modal on tap; ESC/backdrop close works; hash selection preserved; live-mode shows warning, static does not | -| 5 | Modeling skill: always-on E7b examples step | `skills/noorm-modeling/references/entity-flow.md` (primary surface); `skills/noorm-modeling/SKILL.md` (high-level outline if present); `docs/design/noorm-modeling-skill.md` (mermaid, if it diagrams E-steps); `docs/spec/noorm-modeling-skill.md` (change log) | atomic-builder | 2–4 | entity-flow.md lists E7b between E7 and E8; design mermaid updated if applicable; spec change log records amendment | +| 5 | Modeling skill: always-on E7b examples step | `skills/ignatius-modeling/references/entity-flow.md` (primary surface); `skills/ignatius-modeling/SKILL.md` (high-level outline if present); `docs/design/ignatius-modeling-skill.md` (mermaid, if it diagrams E-steps); `docs/spec/ignatius-modeling-skill.md` (change log) | atomic-builder | 2–4 | entity-flow.md lists E7b between E7 and E8; design mermaid updated if applicable; spec change log records amendment | | 6 | Broken-demo fixture + test pin-count update | one existing entity under `models/broken-demo/`; `test/checks/test-validate-entity.ts`; any other pinned-count check that asserts broken-demo finding totals | atomic-surgeon | 2–3 | Broken-pin live-mode test count increases by exactly 1; static stderr count unchanged | | 7 | Backfill examples across all 24 `key-inherited` entities | `models/key-inherited/{catalog,identity,reference,transactional}/*.md` | atomic-builder | 24 | Clean-baseline test still reports 0 findings; entity files retain existing frontmatter; each `examples:` block has ≥2 rows with values drawn from the entity's domain (not "foo/bar") | @@ -121,7 +121,7 @@ Built across 7 checkpoint iterations of `/subagent-implementation`, then squashe - CP-2 validator rule + `liveOnly` filter (`src/validate.ts`, `test/checks/test-validate-examples.ts`) - CP-3 dict accordion + static-surface findings filter (`src/generators/dict.ts`, `src/server.ts`, `test/checks/test-dict-examples.ts`, `test/visual/screenshot-dict-examples.ts`) - CP-4 graph entity-detail modal accordion + decoupled close (`src/App.tsx`, `src/styles.css`, `test/visual/screenshot-entity-modal.ts`) - - CP-5 always-on E7b skill step (`skills/noorm-modeling/references/entity-flow.md`, `skills/noorm-modeling/references/verification.md`, `docs/design/noorm-modeling-skill.md`, `docs/spec/noorm-modeling-skill.md` change log) + - CP-5 always-on E7b skill step (`skills/ignatius-modeling/references/entity-flow.md`, `skills/ignatius-modeling/references/verification.md`, `docs/design/ignatius-modeling-skill.md`, `docs/spec/ignatius-modeling-skill.md` change log) - CP-6 broken-demo Customer.md amend + test pin update (`models/broken-demo/Customer.md`, `test/checks/test-validate-refs.ts`, `test/checks/test-api-model.ts`) - CP-7 24-entity backfill under `models/key-inherited/{catalog,identity,reference,transactional}/` @@ -132,7 +132,7 @@ Built across 7 checkpoint iterations of `/subagent-implementation`, then squashe **Unforeseens — surprises that emerged during implementation:** - An entity-detail modal already existed in `src/App.tsx:276` (`SelectedEntityModal`); CP-4 reduced from "build the modal" to "add the examples accordion + decouple close from selection". - `generateDict`'s `mode` param turned out to be theme (`dark`/`light`), not surface — CP-3 required adding an explicit `surface?: 'live' | 'static'` opt to distinguish CLI-static from server-live. -- `origin/main` had advanced ten commits past the branch base while the loop was running, including a rename of `skills/ignatius-modeling/` → `skills/noorm-modeling/` and a `feat(cli): add validate subcommand`. The rebase merged my CP-5 edits into the renamed paths automatically. +- `origin/main` had advanced ten commits past the branch base while the loop was running, including a rename of `skills/ignatius-modeling/` → `skills/ignatius-modeling/` and a `feat(cli): add validate subcommand`. The rebase merged my CP-5 edits into the renamed paths automatically. **Deferred items still open:** - None. The four cosmetic nits (F-2 through F-5) in the in-loop FOLLOWUPS ledger were stylistic and dropped — they all reflected choices consistent with the file's existing conventions. The scratchpad is deleted at the end of finalization. diff --git a/docs/spec/folder-model.md b/docs/spec/folder-model.md index db893e5..f1f0ba4 100644 --- a/docs/spec/folder-model.md +++ b/docs/spec/folder-model.md @@ -57,14 +57,14 @@ layout. Implements #16. See `docs/design/folder-model.md`. - [ ] Every test that builds a temp fixture with `_groups`/`_externals`/`_stores` dirs is updated to the new folder names (≈9 tests). No test references a `_*` model path. `bun run test` exits 0; `bun run build:cli` succeeds. -- [ ] The `noorm-modeling` skill teaches the new layout everywhere: no +- [ ] The `ignatius-modeling` skill teaches the new layout everywhere: no `_groups`/`_externals`/`_stores`/`flows/_*` path instruction remains in - `skills/noorm-modeling/**`. The model-bootstrap and entity-write steps write under + `skills/ignatius-modeling/**`. The model-bootstrap and entity-write steps write under `data/` and `groups/`; DFD authoring references root `externals/` + `stores/`. - [ ] Public guides `docs/guides/folder-format.md` and `docs/guides/flows.md` describe the new layout (tree sketches + prose). The live-contract design/specs the skill cites are amended per spec-currency: `markdown-driven-erd` (design), - `ignatius-project-config` (design), `noorm-modeling-skill` (design+spec), + `ignatius-project-config` (design), `ignatius-modeling-skill` (design+spec), `process-flows` (design+spec), `noorm-flow-discovery` (design). CLAUDE.md gets a new "Folder model" feature-map row; `docs/glossary.md` reconciled. - [ ] Touched source files introduce **zero** new `tsc --noEmit` errors vs. baseline. @@ -75,8 +75,8 @@ layout. Implements #16. See `docs/design/folder-model.md`. |---|------------|-------------|-------|------------|----------| | 1 | Entity side: parser scans `data/**`, reads optional `groups/`; migrate entities + `_groups` in all 8 roots; update entity-fixture-creating tests | `src/model/parse.ts`, all 8 model roots (entities + `_groups`), test-branding-parse / test-config-yaml / test-parse-examples / test-parse-globals / test-parse-predicate / test-theme-parse / test-cli-stderr / screenshot-entity-modal | atomic-implementer (feature) | ~12 + moves | entity tests + `validate` green; flow tests still green (flows untouched); groups-less model parses | | 2 | Flow side: parser reads root `externals/`+`stores/`, drops per-DFD scans + `_` skip; validator msgs; migrate every `_externals`/`_stores` dir to model-root registries (collapsing same-name collisions in `broken-flow` + `flows-leveling`); update flow-fixture tests incl. removed-override assertions | `src/flows/flow-parse.ts`, `src/model/validate.ts`, flows trees in models/key-inherited, models/llm-memory-db-mssql, test/fixtures/{flows-model, broken-flows-model, broken-flow, flows-leveling, flows}; tests test-cp5-title-override, test-parse-flows, test-validate-flows, test-flow-cli | atomic-implementer (feature) | ~12 + moves | flow tests + `validate` green on all flow models; full `bun run test` exit 0; counts re-verified; broken fixtures keep finding sets | -| 3 | Skill: rewrite all stale path instructions to the new layout | `skills/noorm-modeling/references/{entity-flow,model-flow,dfd-authoring,flow-templates,interviewing,reverse-engineering,templates,verification}.md`, `SKILL.md` if needed | atomic-implementer (feature) | ~8 | no `_groups`/`_externals`/`_stores`/`flows/_*` grep hit in `skills/`; bootstrap+entity+DFD steps point at new folders | -| 4 | Public docs + canonical specs/designs + CLAUDE.md + glossary | `docs/guides/folder-format.md`, `docs/guides/flows.md`, amend `docs/design/{markdown-driven-erd,ignatius-project-config,noorm-modeling-skill,process-flows,noorm-flow-discovery}.md` + `docs/spec/{noorm-modeling-skill,process-flows}.md`, `CLAUDE.md` feature map, `docs/glossary.md` | atomic-implementer (surgical→feature) | ~10 | no stale `_*`/per-DFD layout in guides; spec-currency clean; new feature-map row present | +| 3 | Skill: rewrite all stale path instructions to the new layout | `skills/ignatius-modeling/references/{entity-flow,model-flow,dfd-authoring,flow-templates,interviewing,reverse-engineering,templates,verification}.md`, `SKILL.md` if needed | atomic-implementer (feature) | ~8 | no `_groups`/`_externals`/`_stores`/`flows/_*` grep hit in `skills/`; bootstrap+entity+DFD steps point at new folders | +| 4 | Public docs + canonical specs/designs + CLAUDE.md + glossary | `docs/guides/folder-format.md`, `docs/guides/flows.md`, amend `docs/design/{markdown-driven-erd,ignatius-project-config,ignatius-modeling-skill,process-flows,noorm-flow-discovery}.md` + `docs/spec/{ignatius-modeling-skill,process-flows}.md`, `CLAUDE.md` feature map, `docs/glossary.md` | atomic-implementer (surgical→feature) | ~10 | no stale `_*`/per-DFD layout in guides; spec-currency clean; new feature-map row present | ## Risks @@ -93,8 +93,8 @@ layout. Implements #16. See `docs/design/folder-model.md`. - CP1 — entity scan confined to `data/**`; `_groups/` → optional `groups/` (a missing dir no longer throws); migrated all 8 model roots entity-side via `git mv`; updated the fixture-creating tests; new `test/checks/test-folder-model.ts` (`97cf5e3`). Reviewer PASS, 1🔵 (stale `_stores/Sessions.md` strings) deferred into CP2 scope and fixed there. - CP2 — externals/stores read once from model-root `externals/`/`stores/` (optional); per-DFD `_externals`/`_stores` reads + the override capability removed; validator folder-name strings updated; migrated every `_externals`/`_stores` dir, collapsing the `broken-flow` Shopper override and the `flows-leveling` User (×3) same-name collisions to one global definition each (`be578c6`). Reviewer PASS, 1🟡 fixed in-iteration: CP2 had dumped the full external registry into every `diagram.externals` (so context/leaf diagrams rendered all externals). Surgical fix — `diagram.externals` reverted to referenced-and-defined (rendered set); the full registry rides on `FlowModel.externals`, threaded to the validator's `ambiguous_endpoint` + `unknown_external` checks so `broken-flow`'s bare-`Ambiguous` ambiguity and `ext:Nobody` unknown still fire. -- CP3 — `noorm-modeling` skill rewritten across 8 reference files; `grep` for `_groups`/`_externals`/`_stores`/`flows/_` in `skills/` is zero; verified by building a model per the new instructions and validating it (`2688c0b`). Reviewer PASS, 1🔵 ("in the model root") fixed. -- CP4 — `folder-format` + `flows` guides rewritten to the five-folder model; live design/spec contracts (markdown-driven-erd, ignatius-project-config, process-flows, noorm-modeling-skill, noorm-flow-discovery) amended with change-log entries; incidental path refs fixed; CLAUDE.md feature-map row added (`38eacc0`). Reviewer PASS, 0 findings. +- CP3 — `ignatius-modeling` skill rewritten across 8 reference files; `grep` for `_groups`/`_externals`/`_stores`/`flows/_` in `skills/` is zero; verified by building a model per the new instructions and validating it (`2688c0b`). Reviewer PASS, 1🔵 ("in the model root") fixed. +- CP4 — `folder-format` + `flows` guides rewritten to the five-folder model; live design/spec contracts (markdown-driven-erd, ignatius-project-config, process-flows, ignatius-modeling-skill, noorm-flow-discovery) amended with change-log entries; incidental path refs fixed; CLAUDE.md feature-map row added (`38eacc0`). Reviewer PASS, 0 findings. - Verify (on `main` after squash): `bun run test` → 577 PASS, 0 FAIL, exit 0; `build:cli` clean; `ignatius validate` clean on key-inherited (24), orm-pure (24), orm-hybrid (24), llm-memory-db-mssql (38); broken-demo exits 1 as intended. Zero NEW `tsc` errors in touched files (only the systemic Bun-types/`markdown-it` declaration gap). Grep gates: `src/` zero, `skills/` zero, `docs/` only the migration doc + change-log history. **Squashed to d024c43 — 2026-06-17.** Per-iteration SHAs above are historical (unreachable from any branch). Ships as a minor (`0.11.0`; 0.9.0 and 0.10.0 released before this work) per the user version policy. diff --git a/docs/spec/ignatius-modeling-skill.md b/docs/spec/ignatius-modeling-skill.md new file mode 100644 index 0000000..1386411 --- /dev/null +++ b/docs/spec/ignatius-modeling-skill.md @@ -0,0 +1,211 @@ +# Ignatius modeling skill — spec + + +## Goal + +Ship a single Claude Code skill `/ignatius-modeling` that guides a user through authoring an ignatius entity OR bootstrapping a new model via a Q&A loop, encodes IDEF1X rules to prevent lint violations before they occur, writes real files to disk, and verifies the output by invoking the `ignatius` CLI. + + +## Non-goals + +- No linter reimplementation. The skill depends on `schema-lint-and-error-ux` for verification; it does not recheck rules itself. +- No bulk-create (single entity or single model per invocation). +- No model migration from the old YAML format (`scripts/convert-yaml-to-md.ts` covers that). +- No reverse-engineering of an existing entity file into an editable form. +- No CLI sub-command (`ignatius new entity`). Skill is the only invocation surface. +- No templating library dependency. +- No `git add` / `git commit` in the skill. Staging is left to the user. (Resolved from design open question — user controls staging.) + + +## Modes + +The skill takes one positional argument selecting the mode: + +| Invocation | Mode | Output | +|------------|------|--------| +| `/ignatius-modeling entity` | New entity | Single entity `.md` file written under an existing `models/` tree | +| `/ignatius-modeling model` | New model | Skeleton `models/` tree (`groups/`, `data/`, `ignatius.yml` for theme/branding/meta, optional one reference entity) | +| `/ignatius-modeling` (no arg) | Ask | Skill prompts the user to pick `entity` or `model` before continuing | + +## Authoring convention axis + +Both modes ask the user (or inherit from the model) which **authoring convention** the resulting entity/model uses: + +| Convention | Key placement | Renders as | +|------------|---------------|-----------| +| `key-inherited` (IDEF1X) | Parent PK columns propagate into child PK; child PK = parent PK + local discriminator | Dependent / Associative classifications + identifying edges (1:1 vs 1:many decided by whether FK columns *complete* the child PK) | +| `orm-oriented` | Single surrogate `id` PK per entity; parent link is a plain FK column not in the PK | Independent classifications + referential edges (parser's derivation collapses everything to the referential branch) | + +Both conventions render to the same dict + graph surfaces — verified that ORM-oriented and key-inherited representations of the same logical model produce identical topology (per the `ignatius-authoring-skill` follow-up's gather-evidence pass). The skill teaches **key placement**; classification follows automatically from `derive-classification` (see `docs/spec/derive-classification.md`). + +The convention is picked once per model: in `model` mode the user selects at bootstrap and the skill remembers it for subsequent `entity` invocations against that root (inferred by inspecting an existing entity's PK shape — composite PK with FK ⇒ key-inherited; surrogate `id` PK with non-PK FKs ⇒ orm-oriented). In `entity` mode against an existing model with mixed conventions, the skill surfaces the mix and asks which to use for the new entity. + + +## Success criteria + +- `/ignatius-modeling entity` produces a `.md` entity file with zero lint findings on first run for the happy-path inputs the skill was designed to handle (verified by parsing the structured stderr from `ignatius validate`). +- `/ignatius-modeling model` produces a minimal skeleton (`groups/*.md`, `data/`, single `ignatius.yml`, optional one entity) with zero lint findings on first run. +- Both modes ask about the models dir when not determinable from context. +- The skill never asks for `classification` or per-edge `identifying` — both are derived by the parser from key/relationship shape (`docs/spec/derive-classification.md`). The Q&A asks for keys, relationships (with `on` mapping), and an optional `reference: true` flag for classifier/lookup tables. +- When the user picks the `key-inherited` convention and then declares a PK that does not include the parent's PK columns, the skill prompts to either include the parent PK columns (key-inherited) or switch the convention to `orm-oriented` BEFORE writing the file. +- When the user picks the `orm-oriented` convention and then nominates an FK column as part of the PK, the skill prompts to either drop the FK from the PK (orm-oriented) or switch the convention to `key-inherited` BEFORE writing the file. +- After writing, the skill runs `ignatius validate ` (the validate-only quality gate — no HTML output) and surfaces structured findings (one line per finding, ` ` — the format emitted by `src/validate.ts:formatFindingsForStderr`) with a fix-or-skip prompt. +- The verification loop is bounded to 5 attempts per invocation. If the limit is exceeded, the skill surfaces all remaining findings to the user and exits — it does not silently stop. +- When the user opts into custom branding or theme during `model` mode, the resulting `ignatius.yml` carries all required top-level keys for those blocks (dark palette under `theme:`; `title` + `copyright` under `branding:`). +- Skill lives at `skills/ignatius-modeling/SKILL.md` (project-scoped). +- Invoking the skill from outside an ignatius project does not error — the skill asks for the models dir path. +- Invoking with no arg, an unknown arg, or both modes fails gracefully — the skill asks the user to pick `entity` or `model`. + + +## Approach + +Implement a single `SKILL.md` file that encodes both Q&A flows (entity authoring + model bootstrap), the authoring-convention axis (key-inherited vs orm-oriented), and the file schemas described in `docs/design/ignatius-modeling-skill.md` and `docs/design/markdown-driven-erd.md`. The skill body branches on the positional arg early — `entity` enters the entity flow, `model` enters the bootstrap flow, missing/unknown arg asks the user to pick. The skill body references `docs/spec/schema-lint-and-error-ux.md` as the authority on linter rules so the question ordering stays aligned with what the linter flags. The verification loop (CP-3) parses the structured stderr emitted by `src/validate.ts:formatFindingsForStderr` (live in the shipped CLI). + + +## Checkpoints + +| # | Checkpoint | Deliverable | Verifies | +|---|------------|-------------|----------| +| CP-1 | Skill scaffold + entity flow | `skills/ignatius-modeling/SKILL.md` containing skill frontmatter, mode-arg parsing + dispatch, and the entity Q&A flow. Q&A asks: entity id, group, convention (`key-inherited` \| `orm-oriented`), PK columns (with convention-specific guidance), relationships (with `on` mapping), optional alternate keys, columns, optional `reference: true`, optional body description. No `classification` or per-edge `identifying` prompt. Template emits the per-entity markdown frontmatter format documented in `docs/design/markdown-driven-erd.md`. | Invoking `/ignatius-modeling entity` walks the entity Q&A, writes a well-formed entity `.md` file, and `ignatius dict ` exits 0 against the output; convention contradiction (key-inherited convention + PK that omits parent PK cols, OR orm-oriented convention + FK-in-PK) is caught during the flow, not post-write. | +| CP-2 | Model bootstrap flow | Same `SKILL.md` extended with the model-bootstrap Q&A (encoded `groups/*.md` schema and a single `ignatius.yml` covering `name`, optional `theme`, optional `branding`, optional `_meta` fields + file write step). User picks the model's default convention at bootstrap; the choice is recorded in `ignatius.yml` as a comment for the skill to inherit on subsequent `entity` runs against this root. | Invoking `/ignatius-modeling model` walks the bootstrap Q&A, writes the skeleton, and `ignatius validate ` exits 0 against it. | +| CP-3 | Verification loop | `SKILL.md` post-write block runs `ignatius dict `, parses the structured stderr emitted by `src/validate.ts:formatFindingsForStderr` (one line per finding, ` `), reports findings with fix hints (keyed off `RULES[ruleId]` titles), and re-loops (max 5 attempts). | After writing a file with a deliberate lint violation (e.g. missing pk → `entity.missing_pk`), the skill surfaces the finding, offers to revise, and the corrected file passes on the next run; the parsing handles both `error` and `warn` severities. | +| CP-4 | README update | `README.md` amended with a "Modeling skill" section announcing `/ignatius-modeling`, both modes, the convention axis, prerequisites (Claude Code, `ignatius` binary in PATH), and one example invocation per mode | Section is present and accurate; no broken links. | + + +## Risks + +| Risk | Likelihood | Mitigation | +|------|-----------|-----------| +| `schema-lint-and-error-ux` linter shape changes after the skill ships | Low | The linter has shipped (`src/validate.ts` + `RULES` registry); CP-3 parses its stable structured stderr format. If new rules land, the skill's fix-hint table is the only thing that needs updating. | +| Skill Q&A flow diverges from linter rules over time (rules change, skill body not updated) | Medium | `SKILL.md` includes a frontmatter pointer to `docs/spec/schema-lint-and-error-ux.md`. Sync is manual but explicit — the spec author updates the skill when linter rules change. | +| Convention contradiction detection requires LLM judgment on ambiguous user answers | Medium | Skill encodes the two specific rules (key-inherited convention requires parent PK in child PK; orm-oriented convention forbids FK in PK) as deterministic checks with an explicit re-ask; for ambiguous cases it explains the rule and re-prompts rather than guessing. | +| Mode arg ambiguous or absent | Low | Skill detects missing / unknown arg and prompts the user with the two valid choices before proceeding. | +| `model`-mode skeleton accepted by `parseModels()` but silently wrong | Low | CP-2 Verifies uses `ignatius dict` exit code as the observable signal; any silent parse failures surface as a non-zero exit. | +| Target entity / `groups/` file already exists at the chosen path | Medium | Skill checks for existence before writing; prompts the user to overwrite, choose a different id, or abort. | +| Five-attempt verification loop insufficient for deeply nested lint violations | Low | Five attempts covers the common cases; if exceeded, the skill surfaces all remaining findings and exits, leaving the user to fix manually. | + + +## Change log + + +### 2026-05-29 — Collapse two skills into one + +**What changed:** Spec reframed from two separate skills (`/new-entity` + `/new-model`) into a single `/ignatius-modeling` skill with a positional mode arg (`entity` or `model`). Modes table added. Success criteria updated to reference one skill path. Checkpoints renumbered around the single skill file. + +**Why:** Reviewing the original clarify round: user picked "Both: authoring helper + model bootstrap as **separate sub-modes**" — the label explicitly says "one skill, two args". Initial spec drafted two independent skills, contradicting the user's selection. Amendment reverses that. + +**Superseded:** The prior contract had `/new-entity` and `/new-model` as independent skill files at `.claude/skills/new-entity/SKILL.md` and `.claude/skills/new-model/SKILL.md`. The new contract is one file at `skills/ignatius-modeling/SKILL.md` with mode dispatched by positional arg. + + +### 2026-05-30 — Classification + identifying now derived from keys + +**What changed:** `classification` and per-relationship `identifying` are no longer hand-authored — the parser derives them from PK/FK structure (see `docs/spec/derive-classification.md`, commits `50b6897` + `20c7dd5`). The entity Q&A must NOT ask for classification; it asks for keys + relationships and lets derivation classify. The only surviving hand-authored signal is `reference: true` for classifier/lookup tables. Reconcile flag — full Q&A redesign deferred. + +**Why:** In IDEF1X an identifying relationship ≡ FK-in-PK ≡ dependence. Deriving from keys removes a redundant, unvalidated field and the whole class of declared-vs-structural contradictions. + +**Superseded:** The success criterion "When the user selects classification = independent and then nominates an FK column as part of the PK, the skill prompts to resolve the contradiction" is moot — that contradiction cannot exist when classification is derived from the keys. The entity-flow `Q3: Ask classification` step (design doc) is replaced by deriving classification from the key/relationship answers plus a `reference?` question for lookup tables. + + +### 2026-05-30 — Q&A redesign + authoring-convention axis + linter dependency unblocked + +**What changed:** + +1. **Q&A redesign landed (deferred work from the prior entry).** CP-1 deliverable column rewrites the entity Q&A: no `classification` prompt, no per-edge `identifying` prompt. The Q&A asks entity id → group → convention → PK columns → relationships (with `on`) → columns → optional `reference: true` → optional body. Templates emit the per-entity markdown frontmatter format from `docs/design/markdown-driven-erd.md`. +2. **Authoring-convention axis added.** A new `## Authoring convention axis` body section above Success criteria defines `key-inherited` vs `orm-oriented` and how the skill picks one. Both conventions render identically to dict + graph (verified by gather-evidence per the `ignatius-authoring-skill` follow-up); the skill teaches key placement and lets derivation classify. +3. **Success criteria.** The "independent + FK-in-PK contradiction" criterion is dropped (mooted by derived classification). Two new convention-contradiction criteria replace it: a key-inherited PK that omits parent PK cols, and an orm-oriented PK that includes an FK column. A new criterion fixes the stderr finding format the skill must parse. +4. **Modes table updated.** Model bootstrap writes a single `ignatius.yml` (per `docs/spec/ignatius-project-config.md`), not the historical split `_theme.yaml` + `_branding.yaml` files which no longer exist. +5. **CP-3 unblocked.** The linter has shipped (`src/validate.ts:formatFindingsForStderr` + the `RULES` registry — verified in repo). Soft-verify caveats removed from CP-1, CP-2, CP-3. CP-3 ships in the same iteration as the rest; no follow-up gate. +6. **Risk table.** "Linter not yet implemented when CP-3 attempted" risk replaced with "linter shape changes after skill ships" (low likelihood, isolated mitigation: skill's fix-hint table). + +**Why:** + +- Follow-up `ignatius-authoring-skill` recorded the user's clarification that the skill teaches two authoring conventions (key-inherited vs orm-oriented) in one skill, both producing markdown — not a code-emission tool. Gather-evidence in the follow-up confirmed both conventions render identically; the skill's value is teaching key placement, not classification. +- The prior amendment flagged "full Q&A redesign deferred" — this entry closes that. +- Signals confirm `formatFindingsForStderr` is live in `src/validate.ts` and called by `src/cli.ts`; the CP-3 dependency is unblocked. + +**Superseded:** + +- **CP-1 deliverable** (prior): "encoded IDEF1X rules + entity `.md` frontmatter template" with classification asked in the flow. The Q&A no longer asks for classification. +- **CP-1 Verifies** (prior): "IDEF1X contradiction (independent + FK-in-PK) is caught during the flow". Replaced with convention-contradiction checks. +- **CP-2 deliverable** (prior): "`_groups/*.md`, `_theme.yaml`, `_branding.yaml` schemas". Replaced with `_groups/*.md` + single `ignatius.yml` per the project-config spec. +- **CP-3** (prior): soft-verify with linter-shipping gate. Replaced with structured-stderr parsing live in the same iteration. +- **CP-1 / CP-2 Verifies "soft-verify until …" caveats** — removed; linter shipped. +- **Risks table row** "`schema-lint-and-error-ux` not yet implemented" — replaced with "linter shape changes after skill ships". + + +### 2026-05-30 — Add optional alternate-keys Q&A step + +**What changed:** CP-1 deliverable now includes an optional alternate-keys (AK) prompt between relationships and columns. The implementation Q&A step is `E6 — Alternate keys (optional)`. Updated success criteria text in the CP-1 row to enumerate the AK step. + +**Why:** During the CP-1 build, iter-1 reviewer flagged AK as unrequested scope (the prior deliverable list did not enumerate it). Orchestrator kept AK in the SKILL.md and amended the spec rather than removing the step — AKs are part of the entity schema (`src/parse.ts` carries `alternateKeys` on `ModelNode`), the parser handles them, and an authoring flow that cannot elicit AKs is incomplete for any non-trivial entity. The change is additive — the step is optional with a y/n gate so default behavior is unchanged for users who don't need AKs. + +**Superseded:** the CP-1 deliverable list no longer omits AK. + + +### 2026-05-31 — Verification gate switched to `ignatius validate` + +**What changed:** The post-write verification loop now runs `ignatius validate ` instead of `ignatius dict -o /tmp/ignatius-skill-check.html`. Success-criteria and verification-loop references updated accordingly. The findings format, severity classes, exit-code semantics (1 on global errors, 0 otherwise), and the 5-attempt bound are unchanged. + +**Why:** A new validate-only subcommand was added to the CLI for exactly this purpose — a fast quality gate that parses + validates without generating HTML or writing a file. Using it removes the throwaway `/tmp` HTML artifact the loop previously produced purely to lint, and removes the unused `-o` requirement. + +**Superseded:** the gate command `ignatius dict -o /tmp/ignatius-skill-check.html` is replaced by `ignatius validate `. + +### 2026-06-17 — Folder model migration (#16): groups/ path and entity location + +**What changed:** All path references updated to the five-folder model (#16). The `model` mode skeleton now writes `groups/` (not `_groups/`) and entities under `data//`. Success criteria and checkpoint rows updated accordingly. + +**Superseded:** `_groups/` as the group definition directory; entity files placed at the model root grouped by folder name without a `data/` container. + + +### 2026-05-31 — Add always-on E7b examples step to entity flow + +**What changed:** `skills/ignatius-modeling/references/entity-flow.md` gains a new step **E7b — Examples** inserted between E7 (Columns) and E8 (Reference table). The step is always-on (not skippable): the skill generates 2–3 example rows using the column definitions and business context gathered so far, shows them to the user, and offers to add more before writing the `examples:` frontmatter block. + +Row authoring guidance encoded in the step: plausible domain values (not `foo/bar`); exercise nullability, classification membership, and FK populations; every row key must be within `pk ∪ columns` (stray keys produce a live-mode `entity.example_unknown_column` warning caught by the existing verification loop). + +`skills/ignatius-modeling/references/verification.md` gains a rule-table entry for `entity.example_unknown_column`, noting it is live-server-only (suppressed by the CLI `dict` subcommand in static mode). + +**Why:** CP-5 of `docs/spec/example-instance-tables.md`. Example rows expose nullability and exclusivity mistakes the structural linter cannot catch; generating them in the authoring flow ensures every new entity arrives in the model with concrete instance data. + +**Superseded:** the "Sample rows" note in step E9 (Business context) was an optional, user-driven aside — "Want to sketch a few sample rows?" The new E7b step replaces that by making example generation the skill's responsibility, not the user's, and anchoring it to the `examples:` frontmatter field (which the parser and dict now render). The E9 note remains for the free-form narrative body, but example rows now live in the structured `examples:` block, not an inline `## Sample rows` markdown section. + + +## Implementation log + + +### v1 — 2026-05-30 + +Built across 4 iterations of `/subagent-implementation`. Commits (chronological): + +- `0faa15c` — spec amendment: Q&A redesign + ORM-vs-key-inherited axis + linter dependency unblocked +- `6f1f8c4` — CP-1 + CP-2 + CP-3: `skills/ignatius-modeling/SKILL.md` (entity flow, model bootstrap, verification loop) +- `7109c3a` — CP-4: README "Modeling skill" section + +**Out-of-scope work performed during this build:** + +- Closed follow-up `model-validation-test-suite` in a preceding commit (`711633b`) — delivered by `schema-lint-and-error-ux`. Not strictly part of this spec but cleaned up adjacent state. +- AK step (`E6`) added to the SKILL.md Q&A — was not in CP-1's enumerated list. Spec amended above to ratify. + +**Unforeseens — surprises that emerged during implementation:** + +- Iter-2 reviewer reported `bun run test` failing. Investigation: the worktree had merge-conflict markers in `src/App.tsx` and `src/styles.css`. Cause: an earlier agent ran `git stash pop` (same incident class as the prior `ignatius-project-config` build), popping a stale `viewer-fab-ux` WIP stash into the working tree. Recovery: located the lost stash via `git fsck --unreachable` (sha `04d68a9`), re-stored it with `git stash store`, restored `src/App.tsx` + `src/styles.css` to HEAD, removed `AUTO_MERGE`. Iter-3 brief added an explicit no-`git stash` guardrail. No work lost. +- Iter-2 reviewer also flagged a "test failure" in `test-parse-globals.ts` that turned out to be assertion-description text the script prints as part of its narrative — a `FAIL:` substring inside a passing-assertion message. False alarm. Documented in iter-3 reviewer brief so future runs don't re-trip on it. +- Iter-1's 🔴 (key-inherited example referenced an entity not in fixture) had a symmetric twin: iter-2's orm-oriented block had the same issue. The iter-2 brief fixed only the explicitly-flagged key-inherited block. Iter-3 closed the orm-oriented case. + +**Deferred items still open:** + +- `F-1` — verification loop's `/tmp/ignatius-skill-check.html` path could collide across concurrent skill invocations. Dropped at finalize: the skill is interactive and serializes naturally; concurrent invocations against the same shell are not a realistic risk. Reopen if it ever surfaces in practice. +- `F-2` — alternate-keys (E6) was unrequested scope per the original CP-1 list. Resolved at finalize: keep + ratify via the 2026-05-30 spec change log entry above. + +No items promoted to project-level follow-ups. + +**Squashed to 3b22569 — 2026-05-30.** Per-iteration SHAs above are historical (unreachable from any branch). + +**Merged into master as 773cfbb — 2026-05-30.** + + +### 2026-08-11 — Rename skill to ignatius-modeling + +**What changed:** The skill renamed `noorm-modeling` → `ignatius-modeling` across its directory (`skills/ignatius-modeling/`), invocation (`/ignatius-modeling `), and install command (`npx skills add … --skill ignatius-modeling`). This spec moved from `docs/spec/noorm-modeling-skill.md`. + +**Why:** The skill ships with and authors ignatius models; the name now matches the product instead of the noorm umbrella. diff --git a/docs/spec/noorm-flow-discovery.md b/docs/spec/noorm-flow-discovery.md index 1bbb329..eec4ffb 100644 --- a/docs/spec/noorm-flow-discovery.md +++ b/docs/spec/noorm-flow-discovery.md @@ -3,7 +3,7 @@ ## Goal -Add two modes to the `noorm-modeling` skill: **`flow`** (structured Q&A authoring of SSADM DFD markdown) and **`discover`** (opt-in Socratic interview that generates both ERD entities and DFDs from a business description). Both produce real files verified by `ignatius validate`. No source changes — skill markdown only. +Add two modes to the `ignatius-modeling` skill: **`flow`** (structured Q&A authoring of SSADM DFD markdown) and **`discover`** (opt-in Socratic interview that generates both ERD entities and DFDs from a business description). Both produce real files verified by `ignatius validate`. No source changes — skill markdown only. ## Non-goals @@ -39,7 +39,7 @@ Add two modes to the `noorm-modeling` skill: **`flow`** (structured Q&A authorin | # | Approach | Sketch | Cost | Risk | |---|----------|--------|------|------| -| A | Two new modes on `noorm-modeling`, reusing SKILL.md + references scaffold | `flow` + `discover` references; SKILL router updated | med | SKILL.md routing grows to 4 modes | +| A | Two new modes on `ignatius-modeling`, reusing SKILL.md + references scaffold | `flow` + `discover` references; SKILL router updated | med | SKILL.md routing grows to 4 modes | | B | Separate `noorm-flows` skill | New skill dir | med | Splits model knowledge; discovery straddles two skills | | C | New validator rules to enforce examples/richness | `flow.*` rules in code | high | User-rejected; blocks half-authored flows | | D | Bake store-kind enum into validator | hard enum | med | User chose skill-side menu | @@ -54,10 +54,10 @@ Add two modes to the `noorm-modeling` skill: **`flow`** (structured Q&A authorin | # | Checkpoint | Files/areas | Agent | Est. files | Verifies | |---|------------|-------------|-------|------------|----------| -| 1 | `flow` mode references + templates + e2e trace | `skills/noorm-modeling/references/dfd-authoring.md`, `references/flow-templates.md` | atomic-builder | 2 | F0–F9 present; no mention of store↔store / ext↔store / ext↔ext / process↔process as things "to avoid" (grep clean); store-kind menu lists exactly `db:`/`cache`/`queue`/`file`/`doc`/`manual`; examples-always with all 3 seeding cases; required context sections; templates' tokens + `examples:`/`rows:` shape match `process-flows.md`; a walkthrough produces files passing `ignatius validate` on a scratch model | -| 2 | `discover` mode reference (five-gate Socratic method) | `skills/noorm-modeling/references/discover-flow.md` | atomic-builder | 1 | Five gates (Identify/Decide/Justify/Derive/Ground) with plain-English forms + internal-only principles; verb-led (entities emitted before flows); incremental write; no banned jargon in user-facing forms (grep clean); emits both entities + flows; routes to reverse-engineering when a real system exists | -| 2b | Reverse-engineering reference (extract from an existing system) | `skills/noorm-modeling/references/reverse-engineering.md` | atomic-builder | 1 | Phased R0–R4 (inventory → ER → DFDs → ground → reconcile through gates); IDEF1X spirit (read-don't-invent, key-migration detection, derive-never-declare); reads→inputs / writes→outputs at column level; surfaces anti-patterns as user decisions, never silent rewrites | -| 3 | SKILL.md router update | `skills/noorm-modeling/SKILL.md` | atomic-surgeon | 1 | `argument-hint` = `[entity|model|flow|discover]`; `flow`/`discover` dispatch lines; bare-arg picker lists four; new modes reference the existing core rules | +| 1 | `flow` mode references + templates + e2e trace | `skills/ignatius-modeling/references/dfd-authoring.md`, `references/flow-templates.md` | atomic-builder | 2 | F0–F9 present; no mention of store↔store / ext↔store / ext↔ext / process↔process as things "to avoid" (grep clean); store-kind menu lists exactly `db:`/`cache`/`queue`/`file`/`doc`/`manual`; examples-always with all 3 seeding cases; required context sections; templates' tokens + `examples:`/`rows:` shape match `process-flows.md`; a walkthrough produces files passing `ignatius validate` on a scratch model | +| 2 | `discover` mode reference (five-gate Socratic method) | `skills/ignatius-modeling/references/discover-flow.md` | atomic-builder | 1 | Five gates (Identify/Decide/Justify/Derive/Ground) with plain-English forms + internal-only principles; verb-led (entities emitted before flows); incremental write; no banned jargon in user-facing forms (grep clean); emits both entities + flows; routes to reverse-engineering when a real system exists | +| 2b | Reverse-engineering reference (extract from an existing system) | `skills/ignatius-modeling/references/reverse-engineering.md` | atomic-builder | 1 | Phased R0–R4 (inventory → ER → DFDs → ground → reconcile through gates); IDEF1X spirit (read-don't-invent, key-migration detection, derive-never-declare); reads→inputs / writes→outputs at column level; surfaces anti-patterns as user decisions, never silent rewrites | +| 3 | SKILL.md router update | `skills/ignatius-modeling/SKILL.md` | atomic-surgeon | 1 | `argument-hint` = `[entity|model|flow|discover]`; `flow`/`discover` dispatch lines; bare-arg picker lists four; new modes reference the existing core rules | | 4 | CLAUDE.md feature-map row | `CLAUDE.md` | atomic-surgeon | 1 | Feature-map row added pointing at this spec + design + the new references (cross-refs inside reference files belong to CP1/CP2, not here) | diff --git a/docs/spec/noorm-modeling-skill.md b/docs/spec/noorm-modeling-skill.md index 1b01b10..aba22b7 100644 --- a/docs/spec/noorm-modeling-skill.md +++ b/docs/spec/noorm-modeling-skill.md @@ -1,204 +1,12 @@ -# Noorm modeling skill — spec +# Noorm modeling skill — spec (moved) -## Goal - -Ship a single Claude Code skill `/noorm-modeling` that guides a user through authoring an ignatius entity OR bootstrapping a new model via a Q&A loop, encodes IDEF1X rules to prevent lint violations before they occur, writes real files to disk, and verifies the output by invoking the `ignatius` CLI. - - -## Non-goals - -- No linter reimplementation. The skill depends on `schema-lint-and-error-ux` for verification; it does not recheck rules itself. -- No bulk-create (single entity or single model per invocation). -- No model migration from the old YAML format (`scripts/convert-yaml-to-md.ts` covers that). -- No reverse-engineering of an existing entity file into an editable form. -- No CLI sub-command (`ignatius new entity`). Skill is the only invocation surface. -- No templating library dependency. -- No `git add` / `git commit` in the skill. Staging is left to the user. (Resolved from design open question — user controls staging.) - - -## Modes - -The skill takes one positional argument selecting the mode: - -| Invocation | Mode | Output | -|------------|------|--------| -| `/noorm-modeling entity` | New entity | Single entity `.md` file written under an existing `models/` tree | -| `/noorm-modeling model` | New model | Skeleton `models/` tree (`groups/`, `data/`, `ignatius.yml` for theme/branding/meta, optional one reference entity) | -| `/noorm-modeling` (no arg) | Ask | Skill prompts the user to pick `entity` or `model` before continuing | - -## Authoring convention axis - -Both modes ask the user (or inherit from the model) which **authoring convention** the resulting entity/model uses: - -| Convention | Key placement | Renders as | -|------------|---------------|-----------| -| `key-inherited` (IDEF1X) | Parent PK columns propagate into child PK; child PK = parent PK + local discriminator | Dependent / Associative classifications + identifying edges (1:1 vs 1:many decided by whether FK columns *complete* the child PK) | -| `orm-oriented` | Single surrogate `id` PK per entity; parent link is a plain FK column not in the PK | Independent classifications + referential edges (parser's derivation collapses everything to the referential branch) | - -Both conventions render to the same dict + graph surfaces — verified that ORM-oriented and key-inherited representations of the same logical model produce identical topology (per the `ignatius-authoring-skill` follow-up's gather-evidence pass). The skill teaches **key placement**; classification follows automatically from `derive-classification` (see `docs/spec/derive-classification.md`). - -The convention is picked once per model: in `model` mode the user selects at bootstrap and the skill remembers it for subsequent `entity` invocations against that root (inferred by inspecting an existing entity's PK shape — composite PK with FK ⇒ key-inherited; surrogate `id` PK with non-PK FKs ⇒ orm-oriented). In `entity` mode against an existing model with mixed conventions, the skill surfaces the mix and asks which to use for the new entity. - - -## Success criteria - -- `/noorm-modeling entity` produces a `.md` entity file with zero lint findings on first run for the happy-path inputs the skill was designed to handle (verified by parsing the structured stderr from `ignatius validate`). -- `/noorm-modeling model` produces a minimal skeleton (`groups/*.md`, `data/`, single `ignatius.yml`, optional one entity) with zero lint findings on first run. -- Both modes ask about the models dir when not determinable from context. -- The skill never asks for `classification` or per-edge `identifying` — both are derived by the parser from key/relationship shape (`docs/spec/derive-classification.md`). The Q&A asks for keys, relationships (with `on` mapping), and an optional `reference: true` flag for classifier/lookup tables. -- When the user picks the `key-inherited` convention and then declares a PK that does not include the parent's PK columns, the skill prompts to either include the parent PK columns (key-inherited) or switch the convention to `orm-oriented` BEFORE writing the file. -- When the user picks the `orm-oriented` convention and then nominates an FK column as part of the PK, the skill prompts to either drop the FK from the PK (orm-oriented) or switch the convention to `key-inherited` BEFORE writing the file. -- After writing, the skill runs `ignatius validate ` (the validate-only quality gate — no HTML output) and surfaces structured findings (one line per finding, ` ` — the format emitted by `src/validate.ts:formatFindingsForStderr`) with a fix-or-skip prompt. -- The verification loop is bounded to 5 attempts per invocation. If the limit is exceeded, the skill surfaces all remaining findings to the user and exits — it does not silently stop. -- When the user opts into custom branding or theme during `model` mode, the resulting `ignatius.yml` carries all required top-level keys for those blocks (dark palette under `theme:`; `title` + `copyright` under `branding:`). -- Skill lives at `skills/noorm-modeling/SKILL.md` (project-scoped). -- Invoking the skill from outside an ignatius project does not error — the skill asks for the models dir path. -- Invoking with no arg, an unknown arg, or both modes fails gracefully — the skill asks the user to pick `entity` or `model`. - - -## Approach - -Implement a single `SKILL.md` file that encodes both Q&A flows (entity authoring + model bootstrap), the authoring-convention axis (key-inherited vs orm-oriented), and the file schemas described in `docs/design/noorm-modeling-skill.md` and `docs/design/markdown-driven-erd.md`. The skill body branches on the positional arg early — `entity` enters the entity flow, `model` enters the bootstrap flow, missing/unknown arg asks the user to pick. The skill body references `docs/spec/schema-lint-and-error-ux.md` as the authority on linter rules so the question ordering stays aligned with what the linter flags. The verification loop (CP-3) parses the structured stderr emitted by `src/validate.ts:formatFindingsForStderr` (live in the shipped CLI). - - -## Checkpoints - -| # | Checkpoint | Deliverable | Verifies | -|---|------------|-------------|----------| -| CP-1 | Skill scaffold + entity flow | `skills/noorm-modeling/SKILL.md` containing skill frontmatter, mode-arg parsing + dispatch, and the entity Q&A flow. Q&A asks: entity id, group, convention (`key-inherited` \| `orm-oriented`), PK columns (with convention-specific guidance), relationships (with `on` mapping), optional alternate keys, columns, optional `reference: true`, optional body description. No `classification` or per-edge `identifying` prompt. Template emits the per-entity markdown frontmatter format documented in `docs/design/markdown-driven-erd.md`. | Invoking `/noorm-modeling entity` walks the entity Q&A, writes a well-formed entity `.md` file, and `ignatius dict ` exits 0 against the output; convention contradiction (key-inherited convention + PK that omits parent PK cols, OR orm-oriented convention + FK-in-PK) is caught during the flow, not post-write. | -| CP-2 | Model bootstrap flow | Same `SKILL.md` extended with the model-bootstrap Q&A (encoded `groups/*.md` schema and a single `ignatius.yml` covering `name`, optional `theme`, optional `branding`, optional `_meta` fields + file write step). User picks the model's default convention at bootstrap; the choice is recorded in `ignatius.yml` as a comment for the skill to inherit on subsequent `entity` runs against this root. | Invoking `/noorm-modeling model` walks the bootstrap Q&A, writes the skeleton, and `ignatius validate ` exits 0 against it. | -| CP-3 | Verification loop | `SKILL.md` post-write block runs `ignatius dict `, parses the structured stderr emitted by `src/validate.ts:formatFindingsForStderr` (one line per finding, ` `), reports findings with fix hints (keyed off `RULES[ruleId]` titles), and re-loops (max 5 attempts). | After writing a file with a deliberate lint violation (e.g. missing pk → `entity.missing_pk`), the skill surfaces the finding, offers to revise, and the corrected file passes on the next run; the parsing handles both `error` and `warn` severities. | -| CP-4 | README update | `README.md` amended with a "Modeling skill" section announcing `/noorm-modeling`, both modes, the convention axis, prerequisites (Claude Code, `ignatius` binary in PATH), and one example invocation per mode | Section is present and accurate; no broken links. | - - -## Risks - -| Risk | Likelihood | Mitigation | -|------|-----------|-----------| -| `schema-lint-and-error-ux` linter shape changes after the skill ships | Low | The linter has shipped (`src/validate.ts` + `RULES` registry); CP-3 parses its stable structured stderr format. If new rules land, the skill's fix-hint table is the only thing that needs updating. | -| Skill Q&A flow diverges from linter rules over time (rules change, skill body not updated) | Medium | `SKILL.md` includes a frontmatter pointer to `docs/spec/schema-lint-and-error-ux.md`. Sync is manual but explicit — the spec author updates the skill when linter rules change. | -| Convention contradiction detection requires LLM judgment on ambiguous user answers | Medium | Skill encodes the two specific rules (key-inherited convention requires parent PK in child PK; orm-oriented convention forbids FK in PK) as deterministic checks with an explicit re-ask; for ambiguous cases it explains the rule and re-prompts rather than guessing. | -| Mode arg ambiguous or absent | Low | Skill detects missing / unknown arg and prompts the user with the two valid choices before proceeding. | -| `model`-mode skeleton accepted by `parseModels()` but silently wrong | Low | CP-2 Verifies uses `ignatius dict` exit code as the observable signal; any silent parse failures surface as a non-zero exit. | -| Target entity / `groups/` file already exists at the chosen path | Medium | Skill checks for existence before writing; prompts the user to overwrite, choose a different id, or abort. | -| Five-attempt verification loop insufficient for deeply nested lint violations | Low | Five attempts covers the common cases; if exceeded, the skill surfaces all remaining findings and exits, leaving the user to fix manually. | +Renamed. Current contract: [`ignatius-modeling-skill.md`](./ignatius-modeling-skill.md). ## Change log -### 2026-05-29 — Collapse two skills into one - -**What changed:** Spec reframed from two separate skills (`/new-entity` + `/new-model`) into a single `/noorm-modeling` skill with a positional mode arg (`entity` or `model`). Modes table added. Success criteria updated to reference one skill path. Checkpoints renumbered around the single skill file. - -**Why:** Reviewing the original clarify round: user picked "Both: authoring helper + model bootstrap as **separate sub-modes**" — the label explicitly says "one skill, two args". Initial spec drafted two independent skills, contradicting the user's selection. Amendment reverses that. - -**Superseded:** The prior contract had `/new-entity` and `/new-model` as independent skill files at `.claude/skills/new-entity/SKILL.md` and `.claude/skills/new-model/SKILL.md`. The new contract is one file at `skills/noorm-modeling/SKILL.md` with mode dispatched by positional arg. - - -### 2026-05-30 — Classification + identifying now derived from keys - -**What changed:** `classification` and per-relationship `identifying` are no longer hand-authored — the parser derives them from PK/FK structure (see `docs/spec/derive-classification.md`, commits `50b6897` + `20c7dd5`). The entity Q&A must NOT ask for classification; it asks for keys + relationships and lets derivation classify. The only surviving hand-authored signal is `reference: true` for classifier/lookup tables. Reconcile flag — full Q&A redesign deferred. - -**Why:** In IDEF1X an identifying relationship ≡ FK-in-PK ≡ dependence. Deriving from keys removes a redundant, unvalidated field and the whole class of declared-vs-structural contradictions. - -**Superseded:** The success criterion "When the user selects classification = independent and then nominates an FK column as part of the PK, the skill prompts to resolve the contradiction" is moot — that contradiction cannot exist when classification is derived from the keys. The entity-flow `Q3: Ask classification` step (design doc) is replaced by deriving classification from the key/relationship answers plus a `reference?` question for lookup tables. - - -### 2026-05-30 — Q&A redesign + authoring-convention axis + linter dependency unblocked - -**What changed:** - -1. **Q&A redesign landed (deferred work from the prior entry).** CP-1 deliverable column rewrites the entity Q&A: no `classification` prompt, no per-edge `identifying` prompt. The Q&A asks entity id → group → convention → PK columns → relationships (with `on`) → columns → optional `reference: true` → optional body. Templates emit the per-entity markdown frontmatter format from `docs/design/markdown-driven-erd.md`. -2. **Authoring-convention axis added.** A new `## Authoring convention axis` body section above Success criteria defines `key-inherited` vs `orm-oriented` and how the skill picks one. Both conventions render identically to dict + graph (verified by gather-evidence per the `ignatius-authoring-skill` follow-up); the skill teaches key placement and lets derivation classify. -3. **Success criteria.** The "independent + FK-in-PK contradiction" criterion is dropped (mooted by derived classification). Two new convention-contradiction criteria replace it: a key-inherited PK that omits parent PK cols, and an orm-oriented PK that includes an FK column. A new criterion fixes the stderr finding format the skill must parse. -4. **Modes table updated.** Model bootstrap writes a single `ignatius.yml` (per `docs/spec/ignatius-project-config.md`), not the historical split `_theme.yaml` + `_branding.yaml` files which no longer exist. -5. **CP-3 unblocked.** The linter has shipped (`src/validate.ts:formatFindingsForStderr` + the `RULES` registry — verified in repo). Soft-verify caveats removed from CP-1, CP-2, CP-3. CP-3 ships in the same iteration as the rest; no follow-up gate. -6. **Risk table.** "Linter not yet implemented when CP-3 attempted" risk replaced with "linter shape changes after skill ships" (low likelihood, isolated mitigation: skill's fix-hint table). - -**Why:** - -- Follow-up `ignatius-authoring-skill` recorded the user's clarification that the skill teaches two authoring conventions (key-inherited vs orm-oriented) in one skill, both producing markdown — not a code-emission tool. Gather-evidence in the follow-up confirmed both conventions render identically; the skill's value is teaching key placement, not classification. -- The prior amendment flagged "full Q&A redesign deferred" — this entry closes that. -- Signals confirm `formatFindingsForStderr` is live in `src/validate.ts` and called by `src/cli.ts`; the CP-3 dependency is unblocked. - -**Superseded:** - -- **CP-1 deliverable** (prior): "encoded IDEF1X rules + entity `.md` frontmatter template" with classification asked in the flow. The Q&A no longer asks for classification. -- **CP-1 Verifies** (prior): "IDEF1X contradiction (independent + FK-in-PK) is caught during the flow". Replaced with convention-contradiction checks. -- **CP-2 deliverable** (prior): "`_groups/*.md`, `_theme.yaml`, `_branding.yaml` schemas". Replaced with `_groups/*.md` + single `ignatius.yml` per the project-config spec. -- **CP-3** (prior): soft-verify with linter-shipping gate. Replaced with structured-stderr parsing live in the same iteration. -- **CP-1 / CP-2 Verifies "soft-verify until …" caveats** — removed; linter shipped. -- **Risks table row** "`schema-lint-and-error-ux` not yet implemented" — replaced with "linter shape changes after skill ships". - - -### 2026-05-30 — Add optional alternate-keys Q&A step - -**What changed:** CP-1 deliverable now includes an optional alternate-keys (AK) prompt between relationships and columns. The implementation Q&A step is `E6 — Alternate keys (optional)`. Updated success criteria text in the CP-1 row to enumerate the AK step. - -**Why:** During the CP-1 build, iter-1 reviewer flagged AK as unrequested scope (the prior deliverable list did not enumerate it). Orchestrator kept AK in the SKILL.md and amended the spec rather than removing the step — AKs are part of the entity schema (`src/parse.ts` carries `alternateKeys` on `ModelNode`), the parser handles them, and an authoring flow that cannot elicit AKs is incomplete for any non-trivial entity. The change is additive — the step is optional with a y/n gate so default behavior is unchanged for users who don't need AKs. - -**Superseded:** the CP-1 deliverable list no longer omits AK. - - -### 2026-05-31 — Verification gate switched to `ignatius validate` - -**What changed:** The post-write verification loop now runs `ignatius validate ` instead of `ignatius dict -o /tmp/ignatius-skill-check.html`. Success-criteria and verification-loop references updated accordingly. The findings format, severity classes, exit-code semantics (1 on global errors, 0 otherwise), and the 5-attempt bound are unchanged. - -**Why:** A new validate-only subcommand was added to the CLI for exactly this purpose — a fast quality gate that parses + validates without generating HTML or writing a file. Using it removes the throwaway `/tmp` HTML artifact the loop previously produced purely to lint, and removes the unused `-o` requirement. - -**Superseded:** the gate command `ignatius dict -o /tmp/ignatius-skill-check.html` is replaced by `ignatius validate `. - -### 2026-06-17 — Folder model migration (#16): groups/ path and entity location - -**What changed:** All path references updated to the five-folder model (#16). The `model` mode skeleton now writes `groups/` (not `_groups/`) and entities under `data//`. Success criteria and checkpoint rows updated accordingly. - -**Superseded:** `_groups/` as the group definition directory; entity files placed at the model root grouped by folder name without a `data/` container. - - -### 2026-05-31 — Add always-on E7b examples step to entity flow - -**What changed:** `skills/noorm-modeling/references/entity-flow.md` gains a new step **E7b — Examples** inserted between E7 (Columns) and E8 (Reference table). The step is always-on (not skippable): the skill generates 2–3 example rows using the column definitions and business context gathered so far, shows them to the user, and offers to add more before writing the `examples:` frontmatter block. - -Row authoring guidance encoded in the step: plausible domain values (not `foo/bar`); exercise nullability, classification membership, and FK populations; every row key must be within `pk ∪ columns` (stray keys produce a live-mode `entity.example_unknown_column` warning caught by the existing verification loop). - -`skills/noorm-modeling/references/verification.md` gains a rule-table entry for `entity.example_unknown_column`, noting it is live-server-only (suppressed by the CLI `dict` subcommand in static mode). - -**Why:** CP-5 of `docs/spec/example-instance-tables.md`. Example rows expose nullability and exclusivity mistakes the structural linter cannot catch; generating them in the authoring flow ensures every new entity arrives in the model with concrete instance data. - -**Superseded:** the "Sample rows" note in step E9 (Business context) was an optional, user-driven aside — "Want to sketch a few sample rows?" The new E7b step replaces that by making example generation the skill's responsibility, not the user's, and anchoring it to the `examples:` frontmatter field (which the parser and dict now render). The E9 note remains for the free-form narrative body, but example rows now live in the structured `examples:` block, not an inline `## Sample rows` markdown section. - - -## Implementation log - - -### v1 — 2026-05-30 - -Built across 4 iterations of `/subagent-implementation`. Commits (chronological): - -- `0faa15c` — spec amendment: Q&A redesign + ORM-vs-key-inherited axis + linter dependency unblocked -- `6f1f8c4` — CP-1 + CP-2 + CP-3: `skills/noorm-modeling/SKILL.md` (entity flow, model bootstrap, verification loop) -- `7109c3a` — CP-4: README "Modeling skill" section - -**Out-of-scope work performed during this build:** - -- Closed follow-up `model-validation-test-suite` in a preceding commit (`711633b`) — delivered by `schema-lint-and-error-ux`. Not strictly part of this spec but cleaned up adjacent state. -- AK step (`E6`) added to the SKILL.md Q&A — was not in CP-1's enumerated list. Spec amended above to ratify. - -**Unforeseens — surprises that emerged during implementation:** - -- Iter-2 reviewer reported `bun run test` failing. Investigation: the worktree had merge-conflict markers in `src/App.tsx` and `src/styles.css`. Cause: an earlier agent ran `git stash pop` (same incident class as the prior `ignatius-project-config` build), popping a stale `viewer-fab-ux` WIP stash into the working tree. Recovery: located the lost stash via `git fsck --unreachable` (sha `04d68a9`), re-stored it with `git stash store`, restored `src/App.tsx` + `src/styles.css` to HEAD, removed `AUTO_MERGE`. Iter-3 brief added an explicit no-`git stash` guardrail. No work lost. -- Iter-2 reviewer also flagged a "test failure" in `test-parse-globals.ts` that turned out to be assertion-description text the script prints as part of its narrative — a `FAIL:` substring inside a passing-assertion message. False alarm. Documented in iter-3 reviewer brief so future runs don't re-trip on it. -- Iter-1's 🔴 (key-inherited example referenced an entity not in fixture) had a symmetric twin: iter-2's orm-oriented block had the same issue. The iter-2 brief fixed only the explicitly-flagged key-inherited block. Iter-3 closed the orm-oriented case. - -**Deferred items still open:** - -- `F-1` — verification loop's `/tmp/ignatius-skill-check.html` path could collide across concurrent skill invocations. Dropped at finalize: the skill is interactive and serializes naturally; concurrent invocations against the same shell are not a realistic risk. Reopen if it ever surfaces in practice. -- `F-2` — alternate-keys (E6) was unrequested scope per the original CP-1 list. Resolved at finalize: keep + ratify via the 2026-05-30 spec change log entry above. - -No items promoted to project-level follow-ups. - -**Squashed to 3b22569 — 2026-05-30.** Per-iteration SHAs above are historical (unreachable from any branch). +### 2026-08-11 — Renamed to ignatius-modeling-skill.md -**Merged into master as 773cfbb — 2026-05-30.** +**What changed:** Spec moved to `docs/spec/ignatius-modeling-skill.md`; the skill itself renamed `noorm-modeling` → `ignatius-modeling`. This stub stays one commit so grep finds both names, then gets deleted. diff --git a/docs/wiki/CLAUDE.md b/docs/wiki/CLAUDE.md index d4e6e59..4bd4fea 100644 --- a/docs/wiki/CLAUDE.md +++ b/docs/wiki/CLAUDE.md @@ -34,7 +34,7 @@ Keep the twelve established domains; do not re-derive or merge them. - frontend — src/app/ - generators — src/generators/ - theme — src/theme/ -- skill — skills/noorm-modeling/ +- skill — skills/ignatius-modeling/ - docs — docs/ - scripts — scripts/ diff --git a/docs/wiki/docs.md b/docs/wiki/docs.md index c9a2d53..4e3c6f2 100644 --- a/docs/wiki/docs.md +++ b/docs/wiki/docs.md @@ -24,10 +24,10 @@ description: Design docs, user guides, research notes, and implementation-contra - [`docs/design/process-flows.md`](../design/process-flows.md) (218L) — design doc for the SSADM DFD subsystem (processes, externals, stores, sub-DFDs). - [`docs/design/schema-lint-and-error-ux.md`](../design/schema-lint-and-error-ux.md) (205L) — design doc for schema lint + error UX. - [`docs/design/key-inheritance-lineage.md`](../design/key-inheritance-lineage.md) (175L, grew from 132L) — design doc for the key-inheritance-lineage feature: key-edge rule (FK ⊆ child PK, subset test), transitive connected-component lineage, DD dotted line + DG shift+hover reveal. Change log's newest entries (2026-08-01) record two corrections: associative/junction entities are now traversal BARRIERS (reachable but never passed through, to stop a hub like `Tag` welding every parent it links into one lineage), and the `?lineage=legacy` URL escape hatch used to A/B that fix was removed once the rule was accepted. -- [`docs/design/noorm-flow-discovery.md`](../design/noorm-flow-discovery.md) (179L) — design doc adding two modes to the `noorm-modeling` skill: `flow` (structured Q&A DFD authoring) and `discover` (Socratic interview generating both ERD entities and DFDs from a business description, including reverse-engineering an external system as an evidence source). +- [`docs/design/noorm-flow-discovery.md`](../design/noorm-flow-discovery.md) (179L) — design doc adding two modes to the `ignatius-modeling` skill: `flow` (structured Q&A DFD authoring) and `discover` (Socratic interview generating both ERD entities and DFDs from a business description, including reverse-engineering an external system as an evidence source). - [`docs/design/unified-app.md`](../design/unified-app.md) (152L) — design doc for the unified SPA collapse. - [`docs/design/branding.md`](../design/branding.md) (160L) — design doc for the branding system. -- [`docs/design/noorm-modeling-skill.md`](../design/noorm-modeling-skill.md) (151L) — design doc for the ignatius modeling skill. +- [`docs/design/ignatius-modeling-skill.md`](../design/ignatius-modeling-skill.md) (151L) — design doc for the ignatius modeling skill. - [`docs/design/viewer-fab-ux.md`](../design/viewer-fab-ux.md) (144L) — design doc for the floating action button UX. - [`docs/design/app-tsx-decomposition.md`](../design/app-tsx-decomposition.md) (142L) — design doc for the `src/App.tsx` → [`src/app/`](../../src/app) decomposition. - [`docs/design/cli-and-outputs.md`](../design/cli-and-outputs.md) (135L) — design doc for CLI modes and the static output approach. @@ -64,7 +64,7 @@ All ten are linked from [`README.md`](../../README.md)'s docs table: - [`docs/guides/flows.md`](../guides/flows.md) (148L) — DFDs: processes, externals, stores, sub-DFDs, SSADM/Gane-Sarson rendering. - [`docs/guides/validation.md`](../guides/validation.md) (113L) — the linter, severity tiers, and where findings surface (live viewer, static dictionary/graph, CLI stderr). - [`docs/guides/themes-and-branding.md`](../guides/themes-and-branding.md) (83L) — `theme`/`branding` blocks in `ignatius.yml`, shared across all three subcommands. -- [`docs/guides/modeling-skill.md`](../guides/modeling-skill.md) (71L) — the `/noorm-modeling` Claude Code skill: entity, flow, model, and discover Q&A modes, verified via `ignatius validate`. +- [`docs/guides/modeling-skill.md`](../guides/modeling-skill.md) (71L) — the `/ignatius-modeling` Claude Code skill: entity, flow, model, and discover Q&A modes, verified via `ignatius validate`. - [`docs/guides/building-from-source.md`](../guides/building-from-source.md) (50L) — Bun build stages (`bun build --compile`), project layout, tests. @@ -85,7 +85,7 @@ All ten are linked from [`README.md`](../../README.md)'s docs table: - [`docs/spec/dd-spotlight-grid.md`](../spec/dd-spotlight-grid.md) (239L) — implementation contract for the DD browse-lens spotlight grid (`spotlight.ts`, `flow-spotlight.ts`, `GridCard`, `SpotlightOverlay`). - [`docs/spec/render-perf-indexing.md`](../spec/render-perf-indexing.md) (231L) — implementation contract for the render-perf-indexing batch: preset-layout cache-skip, ELK cost scaling, O(n²)→Map indexing, ELK-in-worker, `buildModelIndex`. - [`docs/spec/unified-app.md`](../spec/unified-app.md) (216L) — implementation contract for the unified SPA. -- [`docs/spec/noorm-modeling-skill.md`](../spec/noorm-modeling-skill.md) (204L) — implementation contract for the ignatius modeling skill. +- [`docs/spec/ignatius-modeling-skill.md`](../spec/ignatius-modeling-skill.md) (204L) — implementation contract for the ignatius modeling skill. - [`docs/spec/graph-flow-search.md`](../spec/graph-flow-search.md) (199L) — implementation contract for Graph/Flows search (SC1–SC12). - [`docs/spec/unified-app-polish.md`](../spec/unified-app-polish.md) (194L) — implementation contract for the CP1–CP13 unified-app-polish batch. - [`docs/spec/keyboard-nav-shortcuts.md`](../spec/keyboard-nav-shortcuts.md) (189L) — implementation contract for keyboard navigation shortcuts (`resolveShortcut`, `useKeyboardShortcuts`). @@ -125,9 +125,9 @@ Canonical vocabulary table: DG (Data Graph), DD (Data Dictionary), DFD (Data Flo - [`docs/spec/dfd-overhaul.md`](../spec/dfd-overhaul.md) — success criteria C4, C16, C17 are cited by name in the **flow-view** domain ([`src/flow-view/elk-flow-layout.ts`](../../src/flow-view/elk-flow-layout.ts), band-layout contract); all six (C4, C5, C13, C15, C16, C17) are checked directly by tests in **frontend**/root test suites ([`test/checks/test-cp4b-elk-edge-routing.ts`](../../test/checks/test-cp4b-elk-edge-routing.ts), `test-cp4c-single-row-bands.ts`, `test-cp4d-frame-alignment.ts`, `test-elk-flow-positions.ts`, [`test/visual/test-cp2-dfd-edge-labels.ts`](../../test/visual/test-cp2-dfd-edge-labels.ts)). - [`docs/spec/graph-flow-search.md`](../spec/graph-flow-search.md) — SC5 is cited by name in **frontend** ([`src/app/logic/search.ts`](../../src/app/logic/search.ts)) and CP1 by [`test/checks/test-viewer-search.ts`](../../test/checks/test-viewer-search.ts). - [`docs/spec/derive-classification.md`](../spec/derive-classification.md) — cited by name in [`test/checks/test-validate-entity.ts`](../../test/checks/test-validate-entity.ts), covering the **parser**/**validate** domains' classification-derivation rules. -- [`docs/spec/example-instance-tables.md`](../spec/example-instance-tables.md) — named as the "canonical source" by [`skills/noorm-modeling/references/entity-flow.md`](../../skills/noorm-modeling/references/entity-flow.md), coupling this domain to **skill**. -- [`docs/spec/process-flows.md`](../spec/process-flows.md) — its `flow.*` frontmatter/token grammar is matched by [`skills/noorm-modeling/references/flow-templates.md`](../../skills/noorm-modeling/references/flow-templates.md), coupling this domain to **skill**. -- [`docs/guides/themes-and-branding.md`](../guides/themes-and-branding.md) — its worked example is pointed to by [`skills/noorm-modeling/references/model-flow.md`](../../skills/noorm-modeling/references/model-flow.md), coupling this domain to **theme** and **skill**. +- [`docs/spec/example-instance-tables.md`](../spec/example-instance-tables.md) — named as the "canonical source" by [`skills/ignatius-modeling/references/entity-flow.md`](../../skills/ignatius-modeling/references/entity-flow.md), coupling this domain to **skill**. +- [`docs/spec/process-flows.md`](../spec/process-flows.md) — its `flow.*` frontmatter/token grammar is matched by [`skills/ignatius-modeling/references/flow-templates.md`](../../skills/ignatius-modeling/references/flow-templates.md), coupling this domain to **skill**. +- [`docs/guides/themes-and-branding.md`](../guides/themes-and-branding.md) — its worked example is pointed to by [`skills/ignatius-modeling/references/model-flow.md`](../../skills/ignatius-modeling/references/model-flow.md), coupling this domain to **theme** and **skill**. - [`docs/design/markdown-driven-erd.md`](../design/markdown-driven-erd.md) has no [`docs/spec/`](../spec) counterpart — [`docs/wiki/feature-map.md`](feature-map.md)'s own "Markdown entity / folder format" row lists the Spec column as `—`. diff --git a/docs/wiki/feature-map.md b/docs/wiki/feature-map.md index 5c7c049..4d8d316 100644 --- a/docs/wiki/feature-map.md +++ b/docs/wiki/feature-map.md @@ -8,14 +8,14 @@ description: Which design doc, spec, guide, and skill section covers each ignati **Rule: a feature is not done until every surface that covers it is consistent.** When you add or change functionality, update its row below — the design doc (the *why*), the spec (the *contract*), the user guide (the *how*), and the skill section that authors or verifies it. If a change has no row, add one; if it touches a surface not yet listed, add the surface. Drift between these is a reliability bug — the skill teaches one thing, the spec contracts another, the guide documents a third. -Paths are relative to `docs/design/`, `docs/spec/`, `docs/guides/`, and `skills/noorm-modeling/`. This map is the human-facing complement to `.claude/project/signals.md` (which maps domains → source code). +Paths are relative to `docs/design/`, `docs/spec/`, `docs/guides/`, and `skills/ignatius-modeling/`. This map is the human-facing complement to `.claude/project/signals.md` (which maps domains → source code). | Feature | Design | Spec | Guide | Skill | |---------|--------|------|-------|-------| | Folder model (`data/` entities + `flows/` DFDs; `groups/` `externals/` `stores/` at root; no `_*`; #16) | folder-model | folder-model | folder-format, flows | entity-flow + model-flow + dfd-authoring | | Markdown entity / folder format | markdown-driven-erd | — | folder-format | entity-flow E1/E2/E7/E10, templates | | Classification + cardinality derivation | markdown-driven-erd | derive-classification | derivation | conventions (derivation tables) | -| Two-path convention (key-inherited vs orm) | noorm-modeling-skill | noorm-modeling-skill | derivation, modeling-skill | SKILL core rules, entity-flow E3 + E5 nudge, model-flow M3 | +| Two-path convention (key-inherited vs orm) | ignatius-modeling-skill | ignatius-modeling-skill | derivation, modeling-skill | SKILL core rules, entity-flow E3 + E5 nudge, model-flow M3 | | Subtype clusters | markdown-driven-erd | derive-classification, schema-lint-and-error-ux | derivation | entity-flow E5a, templates (subtype example) | | Bidirectional predicates | bidirectional-predicates | bidirectional-predicates | predicates | entity-flow E5 | | Schema lint + error UX (findings) | schema-lint-and-error-ux | schema-lint-and-error-ux | validation | verification (rule table + loop) | @@ -32,9 +32,9 @@ Paths are relative to `docs/design/`, `docs/spec/`, `docs/guides/`, and `skills/ | Help overlay (view-aware orientation modal — "what am I looking at?"; `HelpModal` on the shared `Modal`, switched on `ViewName`; concise term→desc rows: Graph = entity types + layouts + Shift lineage + key-inherited vs surrogate; Dict = lenses + spotlight + Shift lineage + search/focus; Flow = DFD symbols + drill-down/inspect; per-view Keyboard section; footnote to Legend on Graph/Flow. Opened by a top-bar `?` button left of the theme toggle AND the `?` key — `resolveShortcut` returns `{type:'help'}`, resolved after the editable guard but before the bare-key modifier guard since `?` needs Shift, gated off ctrl/meta/alt; `useKeyboardShortcuts` `onHelp`; editable guard keeps `?` inert while typing. Distinct from the symbol `LegendModal`. Tests: `test-shortcuts.ts` T16 + `test/checks/test-help-overlay.ts` Playwright) | help-overlay | help-overlay, keyboard-nav-shortcuts | commands | — | | Graph and Flows search (dim-don't-filter title-first matching with a per-bar body-text toggle; Graph: `search-match`/`search-dim` cytoscape classes, `n of N` count readout, Enter cycles ascending-id matches wrapping via `navigateToEntity`, survives hover/lineage/relayout/SSE refresh; Flows: `searchFlowDiagrams` walks every non-synthetic diagram incl. sub-DFDs, results dropdown grouped by diagram navigates via `selectDiagramById`, in-diagram dim keys off suffix-stripped base token; `/` focuses the active view's search bar (Dictionary via `DictionaryViewHandle.focusSearch()`, unchanged otherwise); bundle-only, no model/layout-store/hash/export-payload writes) | graph-flow-search | graph-flow-search | commands | — | | Graph node position persistence (drag-to-save, reset) | graph-position-persistence | graph-position-persistence | — | — | -| Business-narrative body + existence/cascade rules | markdown-driven-erd | noorm-modeling-skill | modeling-skill | entity-flow E9, templates (body sections) | +| Business-narrative body + existence/cascade rules | markdown-driven-erd | ignatius-modeling-skill | modeling-skill | entity-flow E9, templates (body sections) | | Entity body wiki-links `[[Entity]]` | wiki-entity-links | wiki-entity-links, schema-lint-and-error-ux | folder-format | entity-flow E9 (body authoring) | -| The modeling skill itself | noorm-modeling-skill | noorm-modeling-skill | modeling-skill | SKILL + all references | +| The modeling skill itself | ignatius-modeling-skill | ignatius-modeling-skill | modeling-skill | SKILL + all references | | Skill `flow` + `discover` modes (DFD authoring; Socratic business→model discovery, five gates, generates entities + flows; reverse-engineering from existing DB/code/schema in the IDEF1X spirit) | noorm-flow-discovery | noorm-flow-discovery | modeling-skill, flows | SKILL (4-mode router), dfd-authoring, flow-templates, discover-flow, reverse-engineering | | Example / sample instance tables | example-instance-tables | example-instance-tables | folder-format (example rows) | entity-flow E7b (`examples:` frontmatter) + templates | | SSADM process flows (DFD): parse, 11 `flow.*` rules, in-app Flows view (unified SPA), recursive data-level balancing, client-side drill-down, separate-key persistence, per-node ⓘ dialog + `[[wiki-link]]` routing; `db:` store opens rich entity dialog; process dictionary fused into Dictionary view ◆ | process-flows | process-flows (+ research `ssadm-dfd-rules`) | flows | — | @@ -52,6 +52,6 @@ Paths are relative to `docs/design/`, `docs/spec/`, `docs/guides/`, and `skills/ | Key-inheritance lineage (GENERALIZES #9/CP7 above; corrected to the key-edge connected-component model — `src/app/logic/spotlight-inherited.ts` `buildInheritedConnections` keeps its export name + `InheritedConnection {otherId,direction,via}` shape + `INHERITED_IDENTITY='identity'` so `DictionaryView`/`SpotlightOverlay`/`GraphView` are unchanged; **lineage follows ONLY key edges** — an edge whose child-side FK cols (`Object.keys(edge.on)`) are ALL ⊆ the child PK (`pkByNode.get(edge.source)`), a SUBSET test (FK ⊆ PK, non-empty), NEVER a secondary/non-key FK; this one predicate catches identifying-1:many (FK a PROPER subset of the PK, e.g. `SalesInvoice→Party` on `party_no`) AND subtype member→basetype (FK==full PK) — empirically `edge.identifying`==FK⊆PK on `key-inherited`; **lineage** = transitive connected component over key edges in BOTH directions (undirected), cycle-safe visited map; inherited = lineage − self − direct real-edge neighbours (those render solid); `direction='out'` (DD draws ONE source-out line — single arrowhead at the far/member end, pointing FROM the active card OUT to the member; was `'both'`), `via`=nearest key-edge predecessor on the path (or `INHERITED_IDENTITY`); bundle one per otherId, sort by otherId, singleton lineage → []; **DD inherited lines are SHIFT-GATED (mirrors DG):** in the browse lens the dotted inherited lines appear ONLY while Shift is held over an active (hover/pin) card — `DictionaryView` carries a `shiftHeld` state driven by a document `keydown`/`keyup` pair on `Shift` + a `window` blur reset; the `inheritedConnections` useMemo returns `[]` unless `shiftHeld && activeId`, and the inherited-id foldings into `spotlitIds`/`focusSet` are gated on `shiftHeld` too (no lit/extra-focused inherited cards or off-screen inherited chips without Shift); FK (solid) + flow (dashed) lines are UNCHANGED (plain hover/pin); `SpotlightOverlay` unchanged (renders `inheritedConnections=[]` as zero lines/chips); no longer walks subtype-cluster maps (member→basetype IS a key edge) and no longer calls `buildSpotlightConnections` for de-dup; SUPERSEDES the old subtype-cluster + dependent-identifying-1:1 (FK==full PK + 1:1) + per-member secondary-FK expansion, which over-connected via secondary FKs (`SI_Line→Product`/`→LineItemType`) and missed identifying-1:many lineage; proven on `models/key-inherited`: `SSN` reaches the party-keyed family (`SalesInvoice`/`SI_Line`/`SalesOrder`/`SO_Line`/`PaymentAllocation`…) and EXCLUDES `Product`/`Subscription`/`LineItemType`/`PartyType`, `SI_Line` no longer over-connects, ORM surrogate-PK models have zero lineage. **CP-B (DG dotted lines), SHIFT+HOVER trigger:** lineage is revealed by SHIFT+HOVER, NOT click/select. While Shift is held and the pointer is over a node, `GraphView` `enterLineageHover` calls `drawInheritedEdges` to add EPHEMERAL dotted cytoscape edges (class `inherited`, id `_inherited___`) from the hovered node to each inherited `otherId` present in cy, then `applyFocusTiers`; styled in `styles.ts` (`edge.inherited`: dotted, arrowless, thin) using the new `SPOTLIGHT_LINE_INHERITED[mode]` constant exported from `theme-css-vars.ts` (single source of truth shared with the DD CSS var so DG==DD); endpoints folded into the focus-fade `keep` set so they stay lit. Trigger wiring: `mouseover` branches on `evt.originalEvent?.shiftKey` (shift → lineage, no-shift → plain direct-neighbour fade); `mouseout` exits (`exitLineageHover`); a document-level `Shift` keydown/keyup pair toggles lineage on the live hovered node (`hoveredNodeIdRef`) so holding/releasing Shift while already hovering works; all state in refs (stale-closure-safe), listeners removed in cy-init cleanup. A plain click now SELECTS + opens the modal only (no lineage); select/navigate/panel/hash-restore paths no longer draw lineage. `clearInheritedEdges` (`cy.remove('edge.inherited')`) on mouseout/shift-release/deselect/reselect/reset/applyLayoutMode-before-ELK/no-entity-restore/teardown; never enters model/`layoutFingerprint`/`layout-store`/static-export/ELK — added after layout, removed before re-layout; no-leak unit check (`test-inherited-edges-no-leak.ts`, trigger-agnostic) + Playwright DG check (`test-graph-inherited-edges.ts`: plain click → 0 inherited; shift+hover Identity → dotted rays; mouseout → 0; shift+hover ITIN strictly larger transitive set; plain hover → 0; deselect → 0) + visual screenshot (`test/visual/test-graph-inherited-lines.ts`: SSN + SI_Line owner cases via shift+hover). **3-tier focus opacity:** `GraphView` `applyFocusTiers(focusNode)` (run on shift+hover lineage + plain hover; cleared on mouseout/shift-release/deselect/reselect/relayout/teardown) splits the focused state into DIRECT (focused node + its REAL graph neighbors via `connectedEdges().not('.inherited')` + identifying lineage/descendants + joiners → opacity **1.0**), INHERITED/ancestral (the `edge.inherited` rays + their target nodes minus direct, `inherited-dim` → **0.5**), UNRELATED (everything else, `faded` → **0.2**); `styles.ts` `.faded` 0.3→0.2, new `.inherited-dim` 0.5, `edge.inherited` opacity 0.85→0.5; direct wins de-dup (`.difference(direct)` + `buildInheritedConnections` already de-dups); visual harness reads per-tier opacity off the live cy and asserts `direct>inherited>unrelated`) | key-inheritance-lineage | key-inheritance-lineage | — | — | | Glossary of app terms (DG/DD/DFD/DE/DS/EE; DS⊃DE) | — | — | `../glossary.md` | — | -◆ **Process flows — implemented and first-class, now an in-app view.** The `ignatius flow` CLI subcommand has been removed; flows are the **Flows** view inside the unified SPA (`serve`) and are included in the single `export -o model.html` file. The process dictionary is fused into the unified **Dictionary** view (no separate `/flow-dict` route). The **flow viewer is a custom SVG renderer** (`src/flow-view/`, separate from the ERD's Cytoscape): Gane-Sarson notation (open-ended `D#` stores, numbered process hubs, green externals), banded DFD layout (hub-and-spoke to stores/externals, no process-to-process, shared store bridging). Every node carries a ⓘ badge — a **`db:` store** opens the rich `SelectedEntityModal` (attributes, relationships, examples) shared with graph nodes; a process / external / non-`db` store opens the plain markdown doc dialog. Flow bodies parse `[[wiki-links]]` that route in-dialog across both flow nodes and ERD entities. `models/key-inherited` carries demo DFDs (`order-to-cash` with a sub-DFD + `refund`). Skill coverage: the `noorm-modeling` skill's `flow` mode authors flow markdown (see the skill-modes row above). Guide coverage: `docs/guides/flows.md` (folder format, process frontmatter, endpoints, sub-DFDs, viewing) plus the flow rule catalog in `docs/guides/validation.md`. See `docs/spec/process-flows.md` Non-goals + the design's Open questions for the deferred set (queue-payload validation, usage index). +◆ **Process flows — implemented and first-class, now an in-app view.** The `ignatius flow` CLI subcommand has been removed; flows are the **Flows** view inside the unified SPA (`serve`) and are included in the single `export -o model.html` file. The process dictionary is fused into the unified **Dictionary** view (no separate `/flow-dict` route). The **flow viewer is a custom SVG renderer** (`src/flow-view/`, separate from the ERD's Cytoscape): Gane-Sarson notation (open-ended `D#` stores, numbered process hubs, green externals), banded DFD layout (hub-and-spoke to stores/externals, no process-to-process, shared store bridging). Every node carries a ⓘ badge — a **`db:` store** opens the rich `SelectedEntityModal` (attributes, relationships, examples) shared with graph nodes; a process / external / non-`db` store opens the plain markdown doc dialog. Flow bodies parse `[[wiki-links]]` that route in-dialog across both flow nodes and ERD entities. `models/key-inherited` carries demo DFDs (`order-to-cash` with a sub-DFD + `refund`). Skill coverage: the `ignatius-modeling` skill's `flow` mode authors flow markdown (see the skill-modes row above). Guide coverage: `docs/guides/flows.md` (folder format, process frontmatter, endpoints, sub-DFDs, viewing) plus the flow rule catalog in `docs/guides/validation.md`. See `docs/spec/process-flows.md` Non-goals + the design's Open questions for the deferred set (queue-payload validation, usage index). **Example instance tables — implemented and reconciled.** Structured `examples:` frontmatter → `ModelNode.examples` (`src/parse.ts`) → dict/graph accordions + the `entity.example_unknown_column` validator rule (live-server-only — `ignatius validate` never prints it, so the skill self-checks example keys at authoring time). The skill authors `examples:` frontmatter (entity-flow E7b, templates); older entities may still carry a prose `## Sample rows` body section, which the skill reads when seeding flow examples but no longer emits. diff --git a/docs/wiki/index.md b/docs/wiki/index.md index f7687b9..4651ed0 100644 --- a/docs/wiki/index.md +++ b/docs/wiki/index.md @@ -79,7 +79,7 @@ No linter or formatter configured in package.json. | frontend | [`src/app/`](../../src/app) | React 19 unified SPA (Graph/Dictionary/Flows views); shell (`App.tsx`) owns state + composition; views own cy/SVG lifecycle; components/logic/hooks/dom layered underneath | [`docs/wiki/frontend.md`](frontend.md) | | generators | [`src/generators/`](../../src/generators) | Unified static HTML export via `generateApp` (single file — graph + dict + flows); sole static generator | [`docs/wiki/generators.md`](generators.md) | | theme | [`src/theme/`](../../src/theme) | ThemeConfig + Branding types, default palettes, flow-kind colors, dark/light merging | [`docs/wiki/theme.md`](theme.md) | -| skill | [`skills/noorm-modeling/`](../../skills/noorm-modeling) | Project-scoped Claude Code skill: Q&A-driven entity/model/DFD authoring, convention-aware, writes files + verifies with `ignatius validate` | [`docs/wiki/skill.md`](skill.md) | +| skill | [`skills/ignatius-modeling/`](../../skills/ignatius-modeling) | Project-scoped Claude Code skill: Q&A-driven entity/model/DFD authoring, convention-aware, writes files + verifies with `ignatius validate` | [`docs/wiki/skill.md`](skill.md) | | docs | [`docs/`](..) (excluding [`docs/wiki/`](.)) | Design docs, user guides, research notes, and implementation-contract specs — 72 markdown files across [`docs/design/`](../design), [`docs/guides/`](../guides), [`docs/research/`](../research), [`docs/spec/`](../spec) | [`docs/wiki/docs.md`](docs.md) | | scripts | [`scripts/`](../../scripts) | Build helpers: stable-names.ts, convert-yaml-to-md.ts; perf/diagnostic tooling: probe.ts, screenshot.ts, gen-synthetic-model.ts, perf-harness.ts | [`docs/wiki/scripts.md`](scripts.md) | diff --git a/docs/wiki/scan.md b/docs/wiki/scan.md index 97a3d19..7433dab 100644 --- a/docs/wiki/scan.md +++ b/docs/wiki/scan.md @@ -34,7 +34,7 @@ │ │ ├── keyboard-nav-shortcuts.md (37b922e, 110L, 5283ch, 5301B) │ │ ├── markdown-driven-erd.md (aa374b7, 333L, 12629ch, 12757B) │ │ ├── noorm-flow-discovery.md (d205c66, 179L, 14142ch, 14240B) -│ │ ├── noorm-modeling-skill.md (a1dd258, 151L, 9973ch, 10027B) +│ │ ├── ignatius-modeling-skill.md (a1dd258, 151L, 9973ch, 10027B) │ │ ├── process-flows.md (7025e11, 218L, 16377ch, 16502B) │ │ ├── schema-lint-and-error-ux.md (66d2f5e, 205L, 15443ch, 15515B) │ │ ├── src-root-organization.md (d6f979d, 49L, 2713ch, 2719B) @@ -80,7 +80,7 @@ │ │ ├── key-inheritance-lineage.md (d04bc27, 372L, 26421ch, 26657B) │ │ ├── keyboard-nav-shortcuts.md (0c00b77, 189L, 16705ch, 16864B) │ │ ├── noorm-flow-discovery.md (4b7f5a8, 83L, 10554ch, 10666B) -│ │ ├── noorm-modeling-skill.md (947190e, 204L, 22457ch, 22582B) +│ │ ├── ignatius-modeling-skill.md (947190e, 204L, 22457ch, 22582B) │ │ ├── process-flows.md (e5e6472, 682L, 83302ch, 83868B) │ │ ├── render-perf-indexing.md (cf067c8, 231L, 17191ch, 17394B) │ │ ├── schema-lint-and-error-ux.md (6a3d652, 141L, 20922ch, 20995B) @@ -195,7 +195,7 @@ │ ├── screenshot.ts (641f151, 82L, 3044ch, 3048B) │ └── stable-names.ts (a69a3aa, 46L, 2038ch, 2040B) ├── skills/ (1) -│ └── noorm-modeling/ (2) +│ └── ignatius-modeling/ (2) │ ├── references/ (10) │ │ ├── conventions.md (89a838d, 41L, 1459ch, 1475B) │ │ ├── dfd-authoring.md (0b2b14f, 244L, 13521ch, 13671B) diff --git a/docs/wiki/scripts.md b/docs/wiki/scripts.md index 9ef97ba..accddbe 100644 --- a/docs/wiki/scripts.md +++ b/docs/wiki/scripts.md @@ -30,7 +30,7 @@ No user-facing Claude Code skill/command artifacts in this domain. - [`scripts/stable-names.ts`](../../scripts/stable-names.ts) is wired into [`package.json`](../../package.json)'s `build:stable-names` script, which `build:cli` depends on; it is also invoked directly as a CI step in [`.github/workflows/ci.yml`](../../.github/workflows/ci.yml) and [`.github/workflows/release-please.yml`](../../.github/workflows/release-please.yml). It reads `dist/static/index.html`, so any change to how the frontend/build pipeline ([`src/app/`](../../src/app)) names or references its hashed bundle entrypoints in the emitted HTML can break its regex match. - [`scripts/gen-synthetic-model.ts`](../../scripts/gen-synthetic-model.ts) is invoked as a subprocess by [`test/checks/test-synthetic-model.ts`](../../test/checks/test-synthetic-model.ts) (run by `bun run test` and CI), by two [`test/visual/`](../../test/visual) scripts (`test-cp5b-edge-paint-on-load.ts`, `test-cp2-preset-layout.ts`), and by [`scripts/perf-harness.ts`](../../scripts/perf-harness.ts). Its emitted entity/group markdown frontmatter schema (`entity`, `group`, `pk`, `columns`, `relationships`, `subtypes`) must stay parseable by the parser domain's `parseModels()` ([`src/model/parse.ts`](../../src/model/parse.ts)) — `test-synthetic-model.ts` asserts exactly that. -- [`scripts/convert-yaml-to-md.ts`](../../scripts/convert-yaml-to-md.ts) writes into `models//.md` using the same entity frontmatter shape the parser domain expects, and its role as the old-format migration path is referenced from the skill domain's design/spec docs ([`docs/design/noorm-modeling-skill.md`](../design/noorm-modeling-skill.md), [`docs/spec/noorm-modeling-skill.md`](../spec/noorm-modeling-skill.md)) as the tool that already covers YAML→markdown migration. +- [`scripts/convert-yaml-to-md.ts`](../../scripts/convert-yaml-to-md.ts) writes into `models//.md` using the same entity frontmatter shape the parser domain expects, and its role as the old-format migration path is referenced from the skill domain's design/spec docs ([`docs/design/ignatius-modeling-skill.md`](../design/ignatius-modeling-skill.md), [`docs/spec/ignatius-modeling-skill.md`](../spec/ignatius-modeling-skill.md)) as the tool that already covers YAML→markdown migration. - [`scripts/perf-harness.ts`](../../scripts/perf-harness.ts) imports `parseModels` directly from the parser domain ([`src/model/parse.ts`](../../src/model/parse.ts)), spawns the cli domain's `src/cli/cli.ts serve` subcommand, and reads the `window.__IGNATIUS_PERF__` global stamped by the frontend/app domain in [`src/app/views/graph/GraphView.tsx`](../../src/app/views/graph/GraphView.tsx) — a rename or removal of that global breaks the harness silently (it would just hang until the 10-minute timeout). - [`scripts/probe.ts`](../../scripts/probe.ts) and [`scripts/screenshot.ts`](../../scripts/screenshot.ts) both target a running dev server (default `http://localhost:3777`, matching the `dev`/`dev:cli` [`package.json`](../../package.json) scripts) and depend on specific DOM structure in the frontend/app domain to find their targets. - No [`package.json`](../../package.json) script wires up `probe.ts`, `screenshot.ts`, `gen-synthetic-model.ts`, `perf-harness.ts`, or `convert-yaml-to-md.ts` directly — only `build:stable-names` → `stable-names.ts` is a first-class [`package.json`](../../package.json) script; the rest are invoked ad hoc via `bun scripts/.ts` per each script's own usage comment, or as subprocesses from test files. diff --git a/docs/wiki/skill.md b/docs/wiki/skill.md index 77b2bb0..ce99d93 100644 --- a/docs/wiki/skill.md +++ b/docs/wiki/skill.md @@ -1,13 +1,13 @@ --- type: Domain -description: Project-scoped Claude Code skill (`/noorm-modeling`) that Q&A-authors ignatius entities, models, DFD flows, and Socratic-discovery models, then verifies with `ignatius validate`. +description: Project-scoped Claude Code skill (`/ignatius-modeling`) that Q&A-authors ignatius entities, models, DFD flows, and Socratic-discovery models, then verifies with `ignatius validate`. --- # skill ## What it does -[`skills/noorm-modeling/SKILL.md`](../../skills/noorm-modeling/SKILL.md) frontmatter: `name: noorm-modeling`, `description: Guided Q&A authoring of ignatius entities, data flow diagrams, and models, plus Socratic discovery. Use when adding entities, flows, or models.`, `argument-hint: "[entity|model|flow|discover]"`, `allowed-tools: Read Write Edit Bash Glob AskUserQuestion`. +[`skills/ignatius-modeling/SKILL.md`](../../skills/ignatius-modeling/SKILL.md) frontmatter: `name: ignatius-modeling`, `description: Guided Q&A authoring of ignatius entities, data flow diagrams, and models, plus Socratic discovery. Use when adding entities, flows, or models.`, `argument-hint: "[entity|model|flow|discover]"`, `allowed-tools: Read Write Edit Bash Glob AskUserQuestion`. Four modes selected by `$ARGUMENTS`: `entity` (add one entity file), `model` (bootstrap a new model skeleton), `flow` (author a DFD for a user who already knows their processes), `discover` (Socratic five-gate interview that generates both entities and flows; routes to `references/reverse-engineering.md` when a real database/codebase/schema exists to read instead of a user description). @@ -15,28 +15,28 @@ Writes real files to disk and, after every write, runs the verification loop in ## Artifacts -- [`skills/noorm-modeling/SKILL.md`](../../skills/noorm-modeling/SKILL.md) — entry point: frontmatter, mode-dispatch list, the eight "Core rules" that apply to all four modes (derive-never-ask, convention-is-derived, adapt-to-user-conventions, existence-rules-survive-key-style, subtype-independence, predicates-carry-meaning, examples-always, capture-the-business-story), and the reference-file index. -- [`skills/noorm-modeling/references/interviewing.md`](../../skills/noorm-modeling/references/interviewing.md) — how to conduct the Q&A, read first, applies to every mode: one question at a time, explain the why, act (write files) rather than just propose, infer from existing files before asking, reflect after verification instead of blind regeneration, self-check before declaring done, prefer the positive form. -- [`skills/noorm-modeling/references/entity-flow.md`](../../skills/noorm-modeling/references/entity-flow.md) — `entity` mode steps E0–E10: locate model root, entity id, group (with a group-creation sub-flow E2a), convention detection (E3, derived default not a mode), PK columns, relationships/predicates with a one-time convention nudge, conditional subtype-cluster step (E5a), alternate keys, columns, always-run examples step (E7b), reference-table flag (E8), business context/rules/lifecycle (E9), write file (E10). -- [`skills/noorm-modeling/references/model-flow.md`](../../skills/noorm-modeling/references/model-flow.md) — `model` mode steps M1–M8: target directory, model name, model purpose (`description:`), default key-style suggestion recorded as an `ignatius.yml` comment, optional theme (dark/light palette, spacing, per-kind flow colors), optional branding, groups, optional bootstrap entity, write skeleton files. -- [`skills/noorm-modeling/references/dfd-authoring.md`](../../skills/noorm-modeling/references/dfd-authoring.md) — `flow` mode steps F0–F9: locate model root and read entities, diagram identity and standalone-vs-decomposition choice, name processes (Title-Case filename = process id), external sources/sinks, the `db:`/`kind:` store fork, per-field data labels, always-run examples (F6), required bodies per node type (F7), recursive sub-DFD decomposition with no depth cap (F8), write + verify (F9). -- [`skills/noorm-modeling/references/flow-templates.md`](../../skills/noorm-modeling/references/flow-templates.md) — the three DFD node file templates (process, external entity at `externals/.md`, non-`db` store at `stores/.md`) plus worked examples (`Collect-Payment.md`, `Customer.md`, `gateway-log.md`); states its frontmatter keys and endpoint tokens match [`docs/spec/process-flows.md`](../spec/process-flows.md). -- [`skills/noorm-modeling/references/discover-flow.md`](../../skills/noorm-modeling/references/discover-flow.md) — `discover` mode: verbs-first shape (find the verbs, derive the nouns, write nouns then verbs), the five gates (Identify, Decide, Justify, Derive, Ground) as plain-English questions, a `` block banning the gates' underlying formal-logic names (excluded middle, law of identity, non-contradiction, sufficient reason, four causes, three-valued logic, falsifiable, syllogism, a priori, ontology) from ever reaching the user, and "crystallize as you go" incremental file-writing. -- [`skills/noorm-modeling/references/reverse-engineering.md`](../../skills/noorm-modeling/references/reverse-engineering.md) — extracting a model from an existing system (live DB/DDL, ORM models, codebase, stored procedures, API spec, sample data) in five IDEF1X-spirit phases R0–R4; explicitly faithful-first ("never silently 'fix' " an anti-pattern during extraction); feeds candidates back through `discover-flow.md`'s five gates. -- [`skills/noorm-modeling/references/conventions.md`](../../skills/noorm-modeling/references/conventions.md) — column type list (`text`, `integer`, `decimal`, `boolean`, `date`, `datetime`, `binary`), column-property table, and the classification/cardinality derivation tables the parser applies (read-only reference — the skill never asks the user for these). -- [`skills/noorm-modeling/references/templates.md`](../../skills/noorm-modeling/references/templates.md) — the entity `.md`, `groups/.md`, and `ignatius.yml` templates, plus worked key-inherited, orm-oriented, business-context, and subtype-cluster (base + member) examples. -- [`skills/noorm-modeling/references/verification.md`](../../skills/noorm-modeling/references/verification.md) — the `ignatius validate` loop: stderr line format, the full entity/parse/edge/cluster/body rule table and the `flow.*` rule table (each row mapped back to the authoring step that produced the finding), retry policy (max 5 attempts, prefilled re-ask rather than blind rewrite), and the post-clean-validate self-check (business context captured, predicates read as true sentences, example rows checked against `pk ∪ columns` since `entity.example_unknown_column` is live-server-only and `validate` never prints it). +- [`skills/ignatius-modeling/SKILL.md`](../../skills/ignatius-modeling/SKILL.md) — entry point: frontmatter, mode-dispatch list, the eight "Core rules" that apply to all four modes (derive-never-ask, convention-is-derived, adapt-to-user-conventions, existence-rules-survive-key-style, subtype-independence, predicates-carry-meaning, examples-always, capture-the-business-story), and the reference-file index. +- [`skills/ignatius-modeling/references/interviewing.md`](../../skills/ignatius-modeling/references/interviewing.md) — how to conduct the Q&A, read first, applies to every mode: one question at a time, explain the why, act (write files) rather than just propose, infer from existing files before asking, reflect after verification instead of blind regeneration, self-check before declaring done, prefer the positive form. +- [`skills/ignatius-modeling/references/entity-flow.md`](../../skills/ignatius-modeling/references/entity-flow.md) — `entity` mode steps E0–E10: locate model root, entity id, group (with a group-creation sub-flow E2a), convention detection (E3, derived default not a mode), PK columns, relationships/predicates with a one-time convention nudge, conditional subtype-cluster step (E5a), alternate keys, columns, always-run examples step (E7b), reference-table flag (E8), business context/rules/lifecycle (E9), write file (E10). +- [`skills/ignatius-modeling/references/model-flow.md`](../../skills/ignatius-modeling/references/model-flow.md) — `model` mode steps M1–M8: target directory, model name, model purpose (`description:`), default key-style suggestion recorded as an `ignatius.yml` comment, optional theme (dark/light palette, spacing, per-kind flow colors), optional branding, groups, optional bootstrap entity, write skeleton files. +- [`skills/ignatius-modeling/references/dfd-authoring.md`](../../skills/ignatius-modeling/references/dfd-authoring.md) — `flow` mode steps F0–F9: locate model root and read entities, diagram identity and standalone-vs-decomposition choice, name processes (Title-Case filename = process id), external sources/sinks, the `db:`/`kind:` store fork, per-field data labels, always-run examples (F6), required bodies per node type (F7), recursive sub-DFD decomposition with no depth cap (F8), write + verify (F9). +- [`skills/ignatius-modeling/references/flow-templates.md`](../../skills/ignatius-modeling/references/flow-templates.md) — the three DFD node file templates (process, external entity at `externals/.md`, non-`db` store at `stores/.md`) plus worked examples (`Collect-Payment.md`, `Customer.md`, `gateway-log.md`); states its frontmatter keys and endpoint tokens match [`docs/spec/process-flows.md`](../spec/process-flows.md). +- [`skills/ignatius-modeling/references/discover-flow.md`](../../skills/ignatius-modeling/references/discover-flow.md) — `discover` mode: verbs-first shape (find the verbs, derive the nouns, write nouns then verbs), the five gates (Identify, Decide, Justify, Derive, Ground) as plain-English questions, a `` block banning the gates' underlying formal-logic names (excluded middle, law of identity, non-contradiction, sufficient reason, four causes, three-valued logic, falsifiable, syllogism, a priori, ontology) from ever reaching the user, and "crystallize as you go" incremental file-writing. +- [`skills/ignatius-modeling/references/reverse-engineering.md`](../../skills/ignatius-modeling/references/reverse-engineering.md) — extracting a model from an existing system (live DB/DDL, ORM models, codebase, stored procedures, API spec, sample data) in five IDEF1X-spirit phases R0–R4; explicitly faithful-first ("never silently 'fix' " an anti-pattern during extraction); feeds candidates back through `discover-flow.md`'s five gates. +- [`skills/ignatius-modeling/references/conventions.md`](../../skills/ignatius-modeling/references/conventions.md) — column type list (`text`, `integer`, `decimal`, `boolean`, `date`, `datetime`, `binary`), column-property table, and the classification/cardinality derivation tables the parser applies (read-only reference — the skill never asks the user for these). +- [`skills/ignatius-modeling/references/templates.md`](../../skills/ignatius-modeling/references/templates.md) — the entity `.md`, `groups/.md`, and `ignatius.yml` templates, plus worked key-inherited, orm-oriented, business-context, and subtype-cluster (base + member) examples. +- [`skills/ignatius-modeling/references/verification.md`](../../skills/ignatius-modeling/references/verification.md) — the `ignatius validate` loop: stderr line format, the full entity/parse/edge/cluster/body rule table and the `flow.*` rule table (each row mapped back to the authoring step that produced the finding), retry policy (max 5 attempts, prefilled re-ask rather than blind rewrite), and the post-clean-validate self-check (business context captured, predicates read as true sentences, example rows checked against `pk ∪ columns` since `entity.example_unknown_column` is live-server-only and `validate` never prints it). ## Docs -- [`docs/design/noorm-modeling-skill.md`](../design/noorm-modeling-skill.md) — original design doc for the `entity`/`model` modes: the problem (hand-written frontmatter, easy-to-miss IDEF1X rules, reactive linting) and goals/non-goals. -- [`docs/spec/noorm-modeling-skill.md`](../spec/noorm-modeling-skill.md) — spec for the `entity`/`model` modes: mode table, non-goals (no linter reimplementation, no bulk-create, no old-YAML-format migration, no reverse-engineering-to-editable-form, no CLI subcommand, no templating dependency, no automatic `git add`/`commit`). +- [`docs/design/ignatius-modeling-skill.md`](../design/ignatius-modeling-skill.md) — original design doc for the `entity`/`model` modes: the problem (hand-written frontmatter, easy-to-miss IDEF1X rules, reactive linting) and goals/non-goals. +- [`docs/spec/ignatius-modeling-skill.md`](../spec/ignatius-modeling-skill.md) — spec for the `entity`/`model` modes: mode table, non-goals (no linter reimplementation, no bulk-create, no old-YAML-format migration, no reverse-engineering-to-editable-form, no CLI subcommand, no templating dependency, no automatic `git add`/`commit`). - [`docs/design/noorm-flow-discovery.md`](../design/noorm-flow-discovery.md) — design doc that added the `flow` and `discover` modes on top of the original `entity`/`model` skill. - [`docs/spec/noorm-flow-discovery.md`](../spec/noorm-flow-discovery.md) — spec for `flow`/`discover`: no new `flow.*` validator rules, skill-markdown-only change, `discover` as the generative counterpart to `/pressure-test`. -- [`docs/guides/modeling-skill.md`](../guides/modeling-skill.md) — user-facing guide: prerequisites (`ignatius` on `$PATH` or built via `bun run build:cli`) and install via `npx skills add https://github.com/noormdev/ignatius --skill noorm-modeling`. +- [`docs/guides/modeling-skill.md`](../guides/modeling-skill.md) — user-facing guide: prerequisites (`ignatius` on `$PATH` or built via `bun run build:cli`) and install via `npx skills add https://github.com/noormdev/ignatius --skill ignatius-modeling`. - [`docs/guides/flows.md`](../guides/flows.md) — user-facing guide to the `flows/` folder layout and process frontmatter that `references/dfd-authoring.md` and `references/flow-templates.md` author against. - [`docs/guides/getting-started.md`](../guides/getting-started.md) — links to `modeling-skill.md` as the recommended way to author entity and flow files. -- [`docs/spec/folder-model.md`](../spec/folder-model.md) — spec that drove a full rewrite of all eight `skills/noorm-modeling/references/*.md` files (plus `SKILL.md`) onto the current five-folder model-root layout (`data/`, `groups/`, `flows/`, `externals/`, `stores/`, `ignatius.yml` — no leading-underscore folder names). +- [`docs/spec/folder-model.md`](../spec/folder-model.md) — spec that drove a full rewrite of all eight `skills/ignatius-modeling/references/*.md` files (plus `SKILL.md`) onto the current five-folder model-root layout (`data/`, `groups/`, `flows/`, `externals/`, `stores/`, `ignatius.yml` — no leading-underscore folder names). ## Coupling diff --git a/models/llm-memory-db-mssql/ignatius.yml b/models/llm-memory-db-mssql/ignatius.yml index 8858019..26db2b1 100644 --- a/models/llm-memory-db-mssql/ignatius.yml +++ b/models/llm-memory-db-mssql/ignatius.yml @@ -1,5 +1,5 @@ # Default key style: orm-oriented -# (a suggestion the /noorm-modeling skill reads when authoring new entities; +# (a suggestion the /ignatius-modeling skill reads when authoring new entities; # individual entities may differ — it is not enforced. Base entities use surrogate # IDENTITY keys (orm-oriented); Task and all subtype/associative tables migrate # keys (key-inherited) — reverse-engineered faithfully from the real SQL Server schema.) diff --git a/skills/noorm-modeling/SKILL.md b/skills/ignatius-modeling/SKILL.md similarity index 99% rename from skills/noorm-modeling/SKILL.md rename to skills/ignatius-modeling/SKILL.md index ce7f002..d45b3db 100644 --- a/skills/noorm-modeling/SKILL.md +++ b/skills/ignatius-modeling/SKILL.md @@ -1,11 +1,11 @@ --- -name: noorm-modeling +name: ignatius-modeling description: Guided Q&A authoring of ignatius entities, data flow diagrams, and models, plus Socratic discovery. Use when adding entities, flows, or models. argument-hint: "[entity|model|flow|discover]" allowed-tools: Read Write Edit Bash Glob AskUserQuestion --- -# Noorm modeling +# Ignatius modeling Guide the user through authoring an ignatius model — entities, data flow diagrams, a new-model bootstrap, or a Socratic discovery session that generates both — writing real files to disk and verifying them with the `ignatius` CLI. diff --git a/skills/noorm-modeling/references/conventions.md b/skills/ignatius-modeling/references/conventions.md similarity index 100% rename from skills/noorm-modeling/references/conventions.md rename to skills/ignatius-modeling/references/conventions.md diff --git a/skills/noorm-modeling/references/dfd-authoring.md b/skills/ignatius-modeling/references/dfd-authoring.md similarity index 100% rename from skills/noorm-modeling/references/dfd-authoring.md rename to skills/ignatius-modeling/references/dfd-authoring.md diff --git a/skills/noorm-modeling/references/discover-flow.md b/skills/ignatius-modeling/references/discover-flow.md similarity index 100% rename from skills/noorm-modeling/references/discover-flow.md rename to skills/ignatius-modeling/references/discover-flow.md diff --git a/skills/noorm-modeling/references/entity-flow.md b/skills/ignatius-modeling/references/entity-flow.md similarity index 100% rename from skills/noorm-modeling/references/entity-flow.md rename to skills/ignatius-modeling/references/entity-flow.md diff --git a/skills/noorm-modeling/references/flow-templates.md b/skills/ignatius-modeling/references/flow-templates.md similarity index 100% rename from skills/noorm-modeling/references/flow-templates.md rename to skills/ignatius-modeling/references/flow-templates.md diff --git a/skills/noorm-modeling/references/interviewing.md b/skills/ignatius-modeling/references/interviewing.md similarity index 100% rename from skills/noorm-modeling/references/interviewing.md rename to skills/ignatius-modeling/references/interviewing.md diff --git a/skills/noorm-modeling/references/model-flow.md b/skills/ignatius-modeling/references/model-flow.md similarity index 100% rename from skills/noorm-modeling/references/model-flow.md rename to skills/ignatius-modeling/references/model-flow.md diff --git a/skills/noorm-modeling/references/reverse-engineering.md b/skills/ignatius-modeling/references/reverse-engineering.md similarity index 100% rename from skills/noorm-modeling/references/reverse-engineering.md rename to skills/ignatius-modeling/references/reverse-engineering.md diff --git a/skills/noorm-modeling/references/templates.md b/skills/ignatius-modeling/references/templates.md similarity index 99% rename from skills/noorm-modeling/references/templates.md rename to skills/ignatius-modeling/references/templates.md index 20c206f..653c8b8 100644 --- a/skills/noorm-modeling/references/templates.md +++ b/skills/ignatius-modeling/references/templates.md @@ -393,7 +393,7 @@ Do not write the literal placeholder — replace `` with the act ```yaml # Default key style: -# (a suggestion the /noorm-modeling skill reads when authoring new entities; +# (a suggestion the /ignatius-modeling skill reads when authoring new entities; # individual entities may differ — it is not enforced) name: # version: "1.0" diff --git a/skills/noorm-modeling/references/verification.md b/skills/ignatius-modeling/references/verification.md similarity index 100% rename from skills/noorm-modeling/references/verification.md rename to skills/ignatius-modeling/references/verification.md diff --git a/test/checks/test-skill-no-repo-paths.ts b/test/checks/test-skill-no-repo-paths.ts index 3200c12..76f7a75 100644 --- a/test/checks/test-skill-no-repo-paths.ts +++ b/test/checks/test-skill-no-repo-paths.ts @@ -1,8 +1,8 @@ /** * test-skill-no-repo-paths.ts — the distributed skill may not cite repo paths. * - * `npx skills add https://github.com/noormdev/ignatius --skill noorm-modeling` - * copies ONLY `skills/noorm-modeling/` into the user's `.claude/skills/`. Nothing + * `npx skills add https://github.com/noormdev/ignatius --skill ignatius-modeling` + * copies ONLY `skills/ignatius-modeling/` into the user's `.claude/skills/`. Nothing * else from this repository lands on their machine, so a `docs/…`, `src/…`, or * `spec/…` path written into SKILL.md or any reference file is a dead link * everywhere but here — and Claude will try to Read it before discovering that.