feat: add DDL duplication, file size, placeholder, and circular dep checkers

DDL duplication checker (structural warning) detects CREATE TABLE
statements duplicated from canonical schema files. File size checker
(structural warning) enforces per-type line limits from FRAMEWORK.md.
Placeholder marker checker (semantic advisory) flags TBD/TODO/FIXME
outside code fences. Circular dependency detection added to dependency
health checker. Extract shared getNonProseLines utility. Update templates
with framework guardrails. Update Feature Composer agent with rules.
Add schema purity check to Semantic Validator agent.

Author: Dean Sharon

assets/templates/decision.md

@@ -47,6 +47,10 @@ Description of alternative and why it was not chosen.
 
 Description of alternative and why it was not chosen.
 
+## Implementation Notes
+
+> Do not duplicate DDL or implementation SQL here. Link to canonical schema files instead.
+
 ## References
 
 - Related documents or external references

assets/templates/schema.md

@@ -9,14 +9,16 @@ description: {{description}}
 
 {{description}}
 
+> **Content guidelines:** This file should contain DDL, constraints, indexes, RLS, and reference data only. Workflows, state machines, behavioral descriptions, and domain logic belong in domain files.
+
 ## Tables
 
 ### {{table_name}}
 
 | Column | Type | Constraints | Description |
 |--------|------|-------------|-------------|
 | id | uuid | PK | Primary identifier |
-| tenant_id | uuid | FK, NOT NULL | Tenant reference |
+| organization_id | uuid | FK, NOT NULL | Organization reference |
 | created_at | timestamp | NOT NULL | Creation timestamp |
 | updated_at | timestamp | NOT NULL | Last update timestamp |
 
@@ -29,11 +31,11 @@ description: {{description}}
 | Name | Columns | Type | Purpose |
 |------|---------|------|---------|
 | {{table_name}}_pkey | id | PRIMARY | Primary key |
-| {{table_name}}_tenant_id_idx | tenant_id | BTREE | Tenant lookup |
+| {{table_name}}_organization_id_idx | organization_id | BTREE | Organization lookup |
 
 ## Constraints
 
-- `tenant_id` must reference a valid tenant
+- `organization_id` must reference a valid organization
 - `created_at` cannot be modified after creation
 
 ## Usage
@@ -45,4 +47,4 @@ import { {{name}} } from 'your-org/database';
 
 ## Related Schemas
 
-- [related-schema](./related-schema.md) - Tenant ownership
+- [related-schema](./related-schema.md) - Organization ownership

plugins/spec-core/agents/feature-composer.md

@@ -268,3 +268,13 @@ Before creating any file, validate:
 3. **Path Valid** - Target path matches component type
 4. **No Duplicates** - File doesn't already exist
 5. **Layer Rules** - Any links in template are valid for layer
+
+## Framework Rules
+
+Generated content must comply with these rules from FRAMEWORK.md:
+
+- **Rule 1 (No Duplication):** Never duplicate content. Always link to the canonical source. If information exists elsewhere, reference it with a markdown link.
+- **Rule 3 (File Size Limits):** schema: 400 lines, pattern: 300 lines, domain-topic: 500 lines, feature: 400 lines. All other types: 500 lines max.
+- **Rule 7 (No DDL in ADRs):** Decision records must not contain CREATE TABLE or other DDL. Link to canonical schema files instead.
+- **Rule 8 (Schema Purity):** Schema files contain structure only — DDL, constraints, indexes, RLS, and reference data. Workflows, state machines, behavioral descriptions, and domain logic belong in domain files.
+- **Rule 9 (No Placeholders):** Do not leave TBD, TODO, FIXME, HACK, or PLACEHOLDER markers in generated content. Use honest stubs with "Under Review" banners if content is not yet decided.

plugins/spec-core/agents/semantic-validator.md

@@ -92,6 +92,33 @@ Concepts or entities mentioned without links to their defining documents.
 - Terms defined in the same file
 - Links that exist but point to a different section
 
+#### d. Schema Purity (for files matching `docs/schemas/*.md`)
+
+Check that content stays within structural scope.
+
+**What counts as a finding:**
+- Workflow descriptions ("when X happens, then Y")
+- State machine transitions ("pending -> resolved -> dismissed")
+- Business rules ("only admins can...")
+- Process flows with multiple steps
+- Behavioral descriptions explaining system reactions to events
+
+**What does NOT count:**
+- DDL (CREATE TABLE, indexes, constraints, RLS policies)
+- Enum value catalogs (list of valid event types, status values)
+- Relationship diagrams (showing foreign key connections)
+- Constraint explanations ("must be unique because...")
+- Column descriptions (what each field stores)
+- "Referenced By" sections
+
+Report format:
+```
+SCHEMA_PURITY
+  File: docs/schemas/events.md
+  Finding: Contains "Alert Status Flow" section describing state transitions
+  Suggestion: Move to appropriate domain file.
+```
+
 ### Step 4: Cross-Domain Analysis
 
 After all groups are analyzed individually, check across domain boundaries:

src/validation/semantic/config.ts

@@ -36,6 +36,10 @@ export interface SemanticConfig {
   domainCoupling: {
     domains: Record<string, string[]>; // domain name → marker terms
   };
+  placeholders?: {
+    enabled: boolean;
+    markers: string[];
+  };
   ignore: string[]; // glob patterns to skip
 }
 
@@ -191,6 +195,22 @@ function validateConfigShape(raw: unknown): string | null {
     }
   }
 
+  // placeholders
+  if (raw['placeholders'] !== undefined) {
+    if (!isRecord(raw['placeholders'])) {
+      return '"placeholders" must be an object';
+    }
+    const ph = raw['placeholders'];
+    if (ph['enabled'] !== undefined && typeof ph['enabled'] !== 'boolean') {
+      return '"placeholders.enabled" must be a boolean';
+    }
+    if (ph['markers'] !== undefined) {
+      if (!Array.isArray(ph['markers']) || !ph['markers'].every((v): v is string => typeof v === 'string')) {
+        return '"placeholders.markers" must be an array of strings';
+      }
+    }
+  }
+
   // ignore
   if (raw['ignore'] !== undefined) {
     if (!Array.isArray(raw['ignore']) || !raw['ignore'].every((v): v is string => typeof v === 'string')) {
@@ -213,6 +233,17 @@ function mergeWithDefaults(raw: Record<string, unknown>): SemanticConfig {
   const cr = isRecord(raw['crossReference']) ? raw['crossReference'] : {};
   const dh = isRecord(raw['dependencyHealth']) ? raw['dependencyHealth'] : {};
   const dc = isRecord(raw['domainCoupling']) ? raw['domainCoupling'] : {};
+  const ph = isRecord(raw['placeholders']) ? raw['placeholders'] : null;
+
+  // Build placeholders config only if present in raw config
+  const placeholdersConfig: { placeholders: { enabled: boolean; markers: string[] } } | Record<string, never> = ph !== null
+    ? {
+        placeholders: {
+          enabled: typeof ph['enabled'] === 'boolean' ? ph['enabled'] : false,
+          markers: Array.isArray(ph['markers']) ? (ph['markers'] as string[]) : [],
+        },
+      }
+    : {};
 
   return {
     terminology: {
@@ -265,6 +296,7 @@ function mergeWithDefaults(raw: Record<string, unknown>): SemanticConfig {
         ? (dc['domains'] as Record<string, string[]>)
         : defaults.domainCoupling.domains,
     },
+    ...placeholdersConfig,
     ignore: Array.isArray(raw['ignore']) ? (raw['ignore'] as string[]) : defaults.ignore,
   };
 }

src/validation/semantic/dependency-health.test.ts

@@ -143,4 +143,84 @@ describe('checkDependencyHealth', () => {
     const issues = checkDependencyHealth(files, config);
     expect(issues).toHaveLength(0);
   });
+
+  it('detects A → B → A circular dependency', () => {
+    const files = new Map([
+      [
+        'docs/domains/auth/overview.md',
+        '---\ntitle: Auth\ndependencies: users\n---\n# Auth',
+      ],
+      [
+        'docs/domains/users/overview.md',
+        '---\ntitle: Users\ndependencies: auth\n---\n# Users',
+      ],
+    ]);
+    const config = makeConfig();
+
+    const issues = checkDependencyHealth(files, config);
+    const circularIssues = issues.filter((i) => i.code === 'CIRCULAR_DEPENDENCY');
+    expect(circularIssues).toHaveLength(1);
+    expect(circularIssues[0]!.message).toContain('auth');
+    expect(circularIssues[0]!.message).toContain('users');
+  });
+
+  it('detects A → B → C → A circular dependency', () => {
+    const files = new Map([
+      [
+        'docs/domains/auth/overview.md',
+        '---\ntitle: Auth\ndependencies: users\n---\n# Auth',
+      ],
+      [
+        'docs/domains/users/overview.md',
+        '---\ntitle: Users\ndependencies: billing\n---\n# Users',
+      ],
+      [
+        'docs/domains/billing/overview.md',
+        '---\ntitle: Billing\ndependencies: auth\n---\n# Billing',
+      ],
+    ]);
+    const config = makeConfig();
+
+    const issues = checkDependencyHealth(files, config);
+    const circularIssues = issues.filter((i) => i.code === 'CIRCULAR_DEPENDENCY');
+    expect(circularIssues).toHaveLength(1);
+    expect(circularIssues[0]!.message).toContain('Circular dependency detected');
+  });
+
+  it('does not report circular dependency for acyclic chains', () => {
+    const files = new Map([
+      [
+        'docs/domains/auth/overview.md',
+        '---\ntitle: Auth\ndependencies: users\n---\n# Auth',
+      ],
+      [
+        'docs/domains/users/overview.md',
+        '---\ntitle: Users\ndependencies: billing\n---\n# Users',
+      ],
+      [
+        'docs/domains/billing/overview.md',
+        '---\ntitle: Billing\n---\n# Billing',
+      ],
+    ]);
+    const config = makeConfig();
+
+    const issues = checkDependencyHealth(files, config);
+    const circularIssues = issues.filter((i) => i.code === 'CIRCULAR_DEPENDENCY');
+    expect(circularIssues).toHaveLength(0);
+  });
+
+  it('detects self-dependency', () => {
+    const files = new Map([
+      [
+        'docs/domains/auth/overview.md',
+        '---\ntitle: Auth\ndependencies: auth\n---\n# Auth',
+      ],
+    ]);
+    const config = makeConfig();
+
+    const issues = checkDependencyHealth(files, config);
+    const circularIssues = issues.filter((i) => i.code === 'CIRCULAR_DEPENDENCY');
+    expect(circularIssues).toHaveLength(1);
+    expect(circularIssues[0]!.message).toContain('auth');
+  });
 });