id3-cli 0.9.1

package/dist/templates/hooks/pre-commit

@@ -0,0 +1,348 @@
+#!/usr/bin/env node
+
+// src/hooks/pre-commit-entry.ts
+import { resolve } from "node:path";
+
+// src/hooks/shared.ts
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { execSync } from "node:child_process";
+
+// src/utils/ascii.ts
+function box(content, options = {}) {
+  const { title, width = 47, padding = 1 } = options;
+  const lines = content.split("\n");
+  const innerWidth = width - 2;
+  const padStr = " ".repeat(padding);
+  const result = [];
+  if (title) {
+    const titleStr = ` ${title} `;
+    const remaining = innerWidth - titleStr.length - 1;
+    result.push(`  \u250C\u2500${titleStr}${"\u2500".repeat(Math.max(0, remaining))}\u2510`);
+  } else {
+    result.push(`  \u250C${"\u2500".repeat(innerWidth)}\u2510`);
+  }
+  result.push(`  \u2502${" ".repeat(innerWidth)}\u2502`);
+  for (const line of lines) {
+    const padded = `${padStr}${line}`;
+    const spaces = innerWidth - padded.length;
+    result.push(`  \u2502${padded}${" ".repeat(Math.max(0, spaces))}\u2502`);
+  }
+  result.push(`  \u2502${" ".repeat(innerWidth)}\u2502`);
+  result.push(`  \u2514${"\u2500".repeat(innerWidth)}\u2518`);
+  return result.join("\n");
+}
+
+// src/hooks/shared.ts
+function parseGitDiff(output) {
+  if (!output.trim()) return [];
+  return output.trim().split("\n").map((line) => {
+    const [status, path] = line.split("	");
+    return { status, path };
+  }).filter((e) => e.path);
+}
+function getCachedDiff() {
+  try {
+    const output = execSync("git diff --cached --name-status", {
+      encoding: "utf-8"
+    });
+    return parseGitDiff(output);
+  } catch {
+    return [];
+  }
+}
+function getCachedFileContent(filePath) {
+  try {
+    return execSync(`git show :${filePath}`, { encoding: "utf-8" });
+  } catch {
+    return null;
+  }
+}
+function isSchemaFile(filePath, patterns) {
+  return patterns.some((pattern) => matchGlob(filePath, pattern));
+}
+function isValidationFile(filePath, patterns) {
+  return patterns.some((pattern) => matchGlob(filePath, pattern));
+}
+function matchGlob(filePath, pattern) {
+  const regex = pattern.replace(/\./g, "\\.").replace(/\*\*/g, "{{GLOBSTAR}}").replace(/\*/g, "[^/]*").replace(/\{\{GLOBSTAR\}\}/g, ".*");
+  return new RegExp(`^${regex}$`).test(filePath) || new RegExp(`(^|/)${regex}$`).test(filePath);
+}
+async function loadHookConfig(projectRoot2) {
+  try {
+    const configPath = join(
+      projectRoot2,
+      ".claude",
+      "hooks",
+      "hook-config.json"
+    );
+    const content = await readFile(configPath, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+function isSkipHooks() {
+  return process.env["IDDD_SKIP_HOOKS"] === "1";
+}
+async function logSkip(projectRoot2) {
+  const { appendFile, mkdir } = await import("node:fs/promises");
+  const logDir = join(projectRoot2, ".iddd");
+  await mkdir(logDir, { recursive: true });
+  const logPath = join(logDir, "skip-history.log");
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  let commitHash = "unknown";
+  try {
+    commitHash = execSync("git rev-parse HEAD", { encoding: "utf-8" }).trim();
+  } catch {
+  }
+  await appendFile(logPath, `${timestamp}	${commitHash}	Hook skipped
+`);
+}
+function printBlock(title, message) {
+  console.error(box(message, { title }));
+}
+function printWarn(title, message) {
+  console.error(box(message, { title }));
+}
+
+// src/hooks/schema-drift.ts
+function analyzeSchemaChanges(diffContent, filePath) {
+  const changes = [];
+  const addedLines = diffContent.split("\n").filter((l) => l.startsWith("+") && !l.startsWith("+++")).map((l) => l.slice(1).trim());
+  for (const line of addedLines) {
+    const createMatch = line.match(/CREATE\s+TABLE\s+(\w+)/i);
+    if (createMatch) {
+      changes.push({
+        type: "add",
+        table: createMatch[1],
+        trivial: false,
+        description: `Table ${createMatch[1]} created`
+      });
+      continue;
+    }
+    const alterAddMatch = line.match(
+      /ALTER\s+TABLE\s+(\w+)\s+ADD\s+(?:COLUMN\s+)?(\w+)/i
+    );
+    if (alterAddMatch) {
+      changes.push({
+        type: "add",
+        table: alterAddMatch[1],
+        column: alterAddMatch[2],
+        trivial: false,
+        description: `Column ${alterAddMatch[1]}.${alterAddMatch[2]} added`
+      });
+      continue;
+    }
+    const dropMatch = line.match(/DROP\s+TABLE\s+(\w+)/i);
+    if (dropMatch) {
+      changes.push({
+        type: "drop",
+        table: dropMatch[1],
+        trivial: false,
+        description: `Table ${dropMatch[1]} dropped`
+      });
+      continue;
+    }
+    const indexMatch = line.match(/CREATE\s+(?:UNIQUE\s+)?INDEX\s+/i);
+    if (indexMatch) {
+      const tableMatch = line.match(/ON\s+(\w+)/i);
+      changes.push({
+        type: "modify",
+        table: tableMatch?.[1] ?? "unknown",
+        trivial: true,
+        description: `Index added`
+      });
+      continue;
+    }
+    const prismaModel = line.match(/^model\s+(\w+)\s*\{/);
+    if (prismaModel) {
+      changes.push({
+        type: "add",
+        table: prismaModel[1],
+        trivial: false,
+        description: `Model ${prismaModel[1]} added`
+      });
+      continue;
+    }
+    const djangoModel = line.match(/^class\s+(\w+)\(.*Model.*\)/);
+    if (djangoModel) {
+      changes.push({
+        type: "add",
+        table: djangoModel[1],
+        trivial: false,
+        description: `Model ${djangoModel[1]} added`
+      });
+      continue;
+    }
+  }
+  return changes;
+}
+async function runSchemaDrift(projectRoot2) {
+  if (isSkipHooks()) {
+    await logSkip(projectRoot2);
+    return true;
+  }
+  const config = await loadHookConfig(projectRoot2);
+  if (!config?.hooks["pre-commit"]["schema-drift"]?.enabled) {
+    return true;
+  }
+  const { monitored_patterns } = config.hooks["pre-commit"]["schema-drift"];
+  const diff = getCachedDiff();
+  const schemaFiles = diff.filter(
+    (e) => isSchemaFile(e.path, monitored_patterns)
+  );
+  if (schemaFiles.length === 0) return true;
+  const catalogModified = diff.some(
+    (e) => e.path === "specs/entity-catalog.md"
+  );
+  const allChanges = [];
+  for (const file of schemaFiles) {
+    const content = getCachedFileContent(file.path);
+    if (content) {
+      allChanges.push(...analyzeSchemaChanges(content, file.path));
+    }
+  }
+  if (allChanges.length === 0) return true;
+  const hasStructural = allChanges.some((c) => !c.trivial);
+  if (catalogModified) {
+    return true;
+  }
+  if (!hasStructural) {
+    printWarn(
+      "\u26A0\uFE0F Schema Change Detected",
+      allChanges.map((c) => c.description).join("\n") + "\n\nConsider updating specs/entity-catalog.md"
+    );
+    return true;
+  }
+  const changeList = allChanges.filter((c) => !c.trivial).map((c) => `  ${c.description}`).join("\n");
+  printBlock(
+    "\u274C Schema Drift Detected",
+    `entity-catalog.md must be updated first.
+
+${changeList}
+
+Run /id3-info-audit or manually update
+specs/entity-catalog.md`
+  );
+  return false;
+}
+
+// src/hooks/rule-check.ts
+import { readFile as readFile2 } from "node:fs/promises";
+import { join as join2 } from "node:path";
+var VALIDATION_PATTERNS = [
+  {
+    regex: /z\.\s*(?:object|string|number|boolean|array|enum)\s*\(/g,
+    label: "zod"
+  },
+  {
+    regex: /yup\.\s*(?:object|string|number|boolean|array)\s*\(/g,
+    label: "yup"
+  },
+  {
+    regex: /Joi\.\s*(?:object|string|number|boolean|array)\s*\(/g,
+    label: "joi"
+  },
+  { regex: /CHECK\s*\(/gi, label: "SQL CHECK" },
+  { regex: /NOT\s+NULL/gi, label: "SQL NOT NULL" },
+  { regex: /ADD\s+.*UNIQUE/gi, label: "SQL UNIQUE" },
+  { regex: /@validator\s*\(/g, label: "pydantic" },
+  { regex: /@field_validator\s*\(/g, label: "pydantic-v2" },
+  { regex: /@Valid/g, label: "java-valid" },
+  { regex: /@NotNull/g, label: "java-notnull" },
+  {
+    regex: /@Column\s*\(\s*.*nullable\s*[:=]\s*false/g,
+    label: "orm-notnull"
+  },
+  { regex: /@IsNotEmpty\s*\(/g, label: "class-validator" },
+  {
+    regex: /body\s*\(\s*['"].*['"]\s*\)\s*\.(?:not|is)/g,
+    label: "express-validator"
+  }
+];
+function detectValidationPatterns(content, filePath) {
+  const detections = [];
+  const lines = content.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.startsWith("+") && content.includes("\n+")) {
+      continue;
+    }
+    const cleanLine = line.replace(/^\+/, "");
+    for (const { regex, label } of VALIDATION_PATTERNS) {
+      regex.lastIndex = 0;
+      if (regex.test(cleanLine)) {
+        detections.push({
+          file: filePath,
+          line: i + 1,
+          content: cleanLine.trim(),
+          pattern: label
+        });
+      }
+    }
+  }
+  return detections;
+}
+async function hasMatchingRule(projectRoot2, detection) {
+  try {
+    const rulesPath = join2(projectRoot2, "docs", "business-rules.md");
+    const rules = await readFile2(rulesPath, "utf-8");
+    return rules.includes("BR-") && rules.length > 200;
+  } catch {
+    return false;
+  }
+}
+async function runRuleCheck(projectRoot2) {
+  if (isSkipHooks()) {
+    await logSkip(projectRoot2);
+    return true;
+  }
+  const config = await loadHookConfig(projectRoot2);
+  if (!config?.hooks["pre-commit"]["rule-check"]?.enabled) {
+    return true;
+  }
+  const { validation_patterns } = config.hooks["pre-commit"]["rule-check"];
+  const diff = getCachedDiff();
+  const validationFiles = diff.filter(
+    (e) => isValidationFile(e.path, validation_patterns)
+  );
+  if (validationFiles.length === 0) return true;
+  const allDetections = [];
+  for (const file of validationFiles) {
+    const content = getCachedFileContent(file.path);
+    if (content) {
+      allDetections.push(...detectValidationPatterns(content, file.path));
+    }
+  }
+  if (allDetections.length === 0) return true;
+  for (const detection of allDetections) {
+    const matched = await hasMatchingRule(projectRoot2, detection);
+    if (!matched) {
+      printWarn(
+        "\u26A0\uFE0F New Validation Detected",
+        `File: ${detection.file}:${detection.line}
+Pattern: ${detection.pattern}
+Content: ${detection.content}
+
+No matching BR-xxx in business-rules.md
+Consider registering this rule.`
+      );
+    }
+  }
+  return true;
+}
+
+// src/hooks/pre-commit-entry.ts
+var projectRoot = resolve(".");
+async function main() {
+  const schemaDriftOk = await runSchemaDrift(projectRoot);
+  if (!schemaDriftOk) {
+    process.exit(1);
+  }
+  await runRuleCheck(projectRoot);
+}
+main().catch((err) => {
+  console.error("IDDD pre-commit hook error:", err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "id3-cli",
+  "version": "0.9.1",
+  "description": "Information Design-Driven Development — installable skill package for AI coding agents",
+  "type": "module",
+  "bin": {
+    "id3-cli": "dist/bin/cli.js"
+  },
+  "files": [
+    "dist/",
+    "templates/"
+  ],
+  "scripts": {
+    "build": "tsc && node dist/scripts/build-hooks.js",
+    "build:cli": "tsc",
+    "build:hooks": "node dist/scripts/build-hooks.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "author": "Bruce Jung <sunghunet@gmail.com>",
+  "license": "MIT",
+  "keywords": [
+    "iddd",
+    "claude-code",
+    "codex",
+    "information-design",
+    "data-modeling",
+    "agent-skills"
+  ],
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "esbuild": "^0.25.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.1.0"
+  }
+}

package/templates/.claude/hooks/hook-config.json

@@ -0,0 +1,34 @@
+{
+  "enabled": true,
+  "hooks": {
+    "pre-commit": {
+      "schema-drift": {
+        "enabled": true,
+        "severity": "block",
+        "monitored_patterns": [
+          "prisma/schema.prisma",
+          "drizzle/**/*.ts",
+          "**/migrations/*.sql",
+          "**/models.py",
+          "**/entities/*.ts",
+          "**/entities/*.java"
+        ]
+      },
+      "rule-check": {
+        "enabled": true,
+        "severity": "warn",
+        "validation_patterns": [
+          "*.schema.ts",
+          "*.validator.*",
+          "**/validators/**"
+        ]
+      }
+    },
+    "post-commit": {
+      "auto-audit": {
+        "enabled": true,
+        "interval_commits": 10
+      }
+    }
+  }
+}

package/templates/.codex/hooks.json

@@ -0,0 +1,40 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node hooks/iddd-schema-drift.js",
+            "statusMessage": "Checking IDDD schema drift"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node hooks/iddd-rule-check.js",
+            "statusMessage": "Checking IDDD business rules"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node hooks/iddd-auto-audit.js",
+            "statusMessage": "IDDD entropy check"
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/.iddd/commit-count

@@ -0,0 +1 @@
+0

package/templates/AGENTS.md

@@ -0,0 +1,204 @@
+# IDDD - Information Design-Driven Development
+
+You are working in a project that follows **IDDD (Information Design-Driven Development)**. The information model is the generative center of all development. Every artifact - requirements, API contracts, screen designs, business rules, tests - is derived from and traceable to `specs/entity-catalog.md`.
+
+**Core principle:** Start from "what information exists?" rather than "what features should we build?"
+
+---
+
+## Core Principles
+
+1. **Information model is the single source of truth.** All code, APIs, UI, and tests are derived from entity-catalog.md and data-model.md. If code disagrees with the spec, the spec wins - update the code, not the spec (unless there is a deliberate model change).
+
+2. **Entity-first identification.** Before writing any code, entities must be identified and documented. New features start with "what entities are involved?" not "what endpoints do we need?"
+
+3. **Data model traceability.** Every column, constraint, and relationship in the codebase must trace back to an entry in entity-catalog.md and data-model.md. Untracked schema elements are considered drift.
+
+4. **Output-first design.** Design what users see (dashboards, reports, lists) before designing inputs (forms, APIs). The output image drives the information model.
+
+5. **Business rules are explicit.** Every validation, constraint, and derivation rule is registered in `docs/business-rules.md` with a BR-xxx identifier. Code-only rules are considered debt.
+
+---
+
+## Required Reference Files
+
+Before starting any task, read these files to understand the current state:
+
+| File | Purpose |
+|------|---------|
+| `specs/entity-catalog.md` | Entity definitions, attributes, relationships, business rule references |
+| `specs/data-model.md` | Mermaid ERD, design decisions, index strategy |
+| `specs/ui-structure.md` | Screen inventory and navigation structure (Phase 2.5) |
+| `specs/ui-design-contract.md` | Visual design contract -- tokens, components, copywriting (Phase 2.5) |
+| `specs/ui-inventory.md` | Current UI structure (brownfield projects) |
+| `docs/business-rules.md` | All business rules (BR-xxx) with enforcement locations |
+| `steering/data-conventions.md` | Naming, typing, PK strategy, and structural conventions |
+| `steering/product.md` | Product vision, scope, and priorities |
+| `docs/domain-glossary.md` | Domain terms and definitions |
+| `docs/info-debt.md` | Known discrepancies and technical debt items |
+| `docs/model-changelog.md` | History of model changes (Keep a Changelog format) |
+
+---
+
+## New Feature Workflow
+
+When adding a new feature, follow this procedure:
+
+1. **Identify entities involved.** Read `specs/entity-catalog.md`. If new entities are needed, run entity identification first.
+2. **Check business rules.** Read `docs/business-rules.md` for relevant BR-xxx rules that govern the feature's behavior.
+3. **Check UI structure.** Read `specs/ui-structure.md` for screen inventory and `specs/ui-design-contract.md` for design tokens.
+4. **Implement following the spec.** Every line of code should trace to a spec entry (entity attribute, relationship, or BR-xxx rule).
+5. **Register new rules.** If new validation logic is added, register it as BR-xxx in `docs/business-rules.md`.
+6. **Update the changelog.** Record what changed in `docs/model-changelog.md`.
+
+---
+
+## Security Rules
+
+1. **Never commit secrets.** Do not add `.env`, credentials, API keys, or tokens to version control.
+2. **Never skip hooks without logging.** Hook bypasses must be recorded and resolved.
+3. **Never modify spec files during implementation.** If implementation reveals a spec gap, escalate - do not silently change the spec.
+4. **Never delete entities from entity-catalog.md without a changelog entry.** Removals must be documented.
+
+---
+
+## Harness Constraints
+
+The project uses automated hooks that enforce information model consistency:
+
+### Schema Drift Detection (severity: BLOCK)
+
+When modifying schema-related files (migrations, ORM definitions, model files), the harness checks whether `specs/entity-catalog.md` has been updated accordingly. If not, the change is **blocked**.
+
+**Required workflow:** Update `specs/entity-catalog.md` first, then modify the schema.
+
+### Rule Check (severity: WARN)
+
+When adding validation logic (Zod, Yup, Joi, Pydantic, @Valid, etc.), the harness checks for a corresponding BR-xxx entry in `docs/business-rules.md`. If missing, you receive a warning.
+
+**Required workflow:** Register the business rule in `docs/business-rules.md` before or alongside the validation code.
+
+### Auto-Audit (severity: INFO)
+
+After every N commits (configurable), the harness runs an automatic audit comparing the codebase against the information model. Review findings at the start of the next session.
+
+### Hook Bypass
+
+- Set `IDDD_SKIP_HOOKS=1` to skip all hooks temporarily.
+- Bypasses are logged to `.iddd/skip-history.log` and reviewed during audits.
+- Avoid bypassing hooks unless absolutely necessary.
+
+---
+
+## Entropy Management
+
+### Version Headers
+
+`specs/entity-catalog.md` and `specs/data-model.md` contain YAML frontmatter:
+
+```yaml
+---
+version: "1.0"
+last_verified: "YYYY-MM-DD"
+phase: "Phase 2 Complete"
+entity_count: N
+rule_count: N
+audit_status: "clean"
+---
+```
+
+- Update `last_verified` whenever the model is audited or verified.
+- If `last_verified` is more than 7 days old, run an audit before proceeding with new work.
+
+### Change Log
+
+Record all model changes in `docs/model-changelog.md` using Keep a Changelog format.
+
+---
+
+## Multi-Agent Workflow
+
+When multiple agents collaborate on this project, use the following role assignments and coordination rules. This workflow applies to both Codex multi-agent orchestration and any platform that supports parallel agent execution.
+
+### Agent Roles
+
+#### spec-generator
+
+**Responsibility:** Transform the information model into implementation-ready specifications.
+
+**Input files:**
+- `specs/entity-catalog.md`
+- `specs/data-model.md`
+- `specs/ui-structure.md`
+- `specs/ui-design-contract.md`
+- `specs/ui-inventory.md`
+- `docs/business-rules.md`
+- `steering/data-conventions.md`
+
+**Output:** Per-entity or per-feature-group `requirements.md` and `api-contracts.md`.
+
+**Rules:**
+- Every requirement must reference an entity-catalog.md entry or BR-xxx rule.
+- Do not invent requirements not grounded in the information model.
+- Follow `steering/data-conventions.md` for naming and typing.
+- Flag ambiguities rather than assuming.
+
+#### implementer
+
+**Responsibility:** Implement code based on specs from spec-generator.
+
+**Input files:** All spec-generator inputs plus spec-generator output.
+
+**Rules:**
+- Commit per entity (one entity per commit with a descriptive message).
+- Follow the project's tech stack and conventions.
+- Enforce every BR-xxx rule at the specified location (DB constraint, application logic, or both).
+- Never modify `specs/` or `docs/` files directly. If a spec gap is discovered, notify spec-generator and qa-reviewer.
+- Each commit is atomic: model + migration + API + validation + tests for one entity.
+
+#### qa-reviewer
+
+**Responsibility:** Verify implementation against the information model.
+
+**Input files:**
+- `specs/entity-catalog.md`
+- `specs/ui-structure.md`
+- `specs/ui-design-contract.md`
+- `docs/business-rules.md`
+
+**Rules:**
+- Check every entity implementation against entity-catalog.md (attributes, types, constraints).
+- Verify all BR-xxx rules are enforced at the correct location.
+- Verify relationships match the ERD (FK placement, delete rules, cardinality).
+- Every finding must cite the specific spec entry that was violated.
+- Approve only when implementation matches the information model.
+
+### Task Generation
+
+1. Read `specs/entity-catalog.md` to extract the entity list.
+2. Create one task per entity.
+3. Analyze FK dependencies from `specs/data-model.md`.
+4. Independent entities run in parallel; dependent entities wait for parents.
+5. Within each wave, assign tasks across agents.
+
+### Coordination Protocol
+
+- spec-generator completes specs before implementer begins work on an entity.
+- implementer completes implementation before qa-reviewer begins review.
+- qa-reviewer rejects with specific findings referencing spec entries; implementer fixes and resubmits.
+- When all entities pass review, the phase is complete.
+
+---
+
+## IDDD Skills
+
+The following skills are available in the `skills/` directory:
+
+| Skill | Phase | Purpose |
+|-------|-------|---------|
+| id3-identify-entities | 0/1 | Discover entities from existing code or structured interview |
+| id3-design-information | 2 | Refine conceptual model into logical model with rules and UI proposals |
+| id3-design-ui | 2.5 | UI structure derivation, visual design contract, mockup generation |
+| id3-spawn-team | 3-5 | Spawn parallel agents for spec generation, implementation, and QA |
+| id3-info-audit | Audit | Comprehensive information model audit against codebase |
+| id3-preview | Utility | Start preview server for ERD, UI mockups, and audit reports |