pi-aia-asf 0.11.0 → 0.12.1

package/CHANGELOG.md

@@ -7,12 +7,68 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.11.0] - 2026-10-12
+## [0.12.1] - 2026-10-14
+
+### Added
+
+- **06j §7 — who enforces the model gate.** The boundary is now written down:
+  ASF states the obligation, and the loop guard enforces completion
+  **generically**. When a change touches persistence, the model obligations are
+  captured as MUST specs (`capture_spec`) and marked `met` with evidence; the
+  guard verifies those specs at settle exactly as it verifies any specification
+  arriving from any source. What crosses the boundary is the **specification**,
+  never the check — the guard does not know what a cascade is and must not have
+  to. SKILL.md's Phase 6 model rule now says so directly, and the anti-pattern
+  list names the alternative ("asking the loop guard to understand the model").
+
+## [0.12.0] - 2026-10-14
 
 ### Added
 
-- (describe changes for 0.11.0)
+- **The model gate (P27)** — ASF now inspects the data model, not only the code
+  shape. A new mandatory reference, `references/06j-data-model.md`, gives the
+  factory what it never had: ownership classes (composition / instance /
+  ledger), a required `asf-model:` declaration for every relationship a change
+  touches (class, owner, survives-parent), model rules **M1–M8**, the legitimate
+  exceptions, and a model Definition of Done. The obligation is the point — a
+  declaration that concludes "`CASCADE` is correct here" is a pass; what the gate
+  refuses is that nobody was asked.
+- **Two objective fitness functions in the Code Health Gate** (`model` level,
+  `lib/code-health/model.mjs`): a cascade declaration with no ownership
+  declaration, and the rebuild-by-delete signature (delete + re-insert of the
+  same table/collection in one window). Built in — no tool to install, so the
+  level can never be skipped for a missing dependency — reporting `file:line`
+  and the fix, waivable only with a greppable `asf-model-accept: <reason>`.
+  Documented as **a tripwire, not an authority**: `scanned: 0` is reported, never
+  hidden, and a clean scan is not a pass.
+- **Store-agnostic by design.** Declarations are recognised across relational,
+  ORM-mapped and document forms, and a project adds its own dialect with
+  `model.extraCascadePatterns` rather than waiting for a release. Where a store
+  exposes no constraint to inspect, the text says plainly that the invariant
+  tests are the only hard gate.
+- **Invariant and non-effect tests (06g §3)** — the missing half of the test
+  doctrine: survival tests with production-shaped data, non-effect assertions on
+  the tables the change does not name, zero-row invariant queries, and two-user
+  authorization tests. Every other rule asked *did the thing you wanted happen?*;
+  these ask *what must not have happened*.
+- **06b Rule 20 — the model is asserted, not assumed**, plus the Rule 10 DoD
+  model line, the `/asf verify` checklist item, a **Data & model questions** lens
+  in `04-adversarial.md`, a **Data model & ownership** table in the plan
+  template, test-first step 6 in `06-implementation.md`, and a **Model drift**
+  anti-pattern (extending a destructive persistence pattern because the file
+  above does it is drift, not precedent).
 
+### Fixed
+
+- **The rule count in `SKILL.md` can no longer silently disagree with 06b.** The
+  suite now derives the count from the `## Rule N —` headings instead of
+  asserting a hardcoded number, so adding a rule no longer requires editing two
+  test files (and a stale index fails).
+- **`docs/research/improvement-proposals.md` header** still claimed "research
+  phase only — no ASF code or docs have been changed" long after P23–P26 had
+  shipped. It now points at `review-decisions.md` as the authoritative record.
+
+## [0.11.0] - 2026-10-12
 
 ### Added
 

package/index.ts

@@ -53,6 +53,7 @@ const QA_CHECKLIST: Array<{ key: string; label: string }> = [
   { key: "specs", label: "Every MUST spec 'met' with concrete evidence" },
   { key: "trace", label: "Spec-to-code traceability: every met spec has outcome → codePath → test" },
   { key: "code-health", label: "Code Health Gate passed (or enabled:false / gate.mode:warn with the report shown)" },
+  { key: "model", label: "Model (06j): every relationship the change touches has a written ownership declaration; store writes have invariant + non-effect tests (06g §3); /asf health model level passes or its findings are accepted with a reason; n/a with reason if no persistence touched" },
   { key: "surface", label: "Every delivered feature is consumed by a surface (UI or API) — nothing dead" },
   { key: "e2e", label: "Feature specs have an end-to-end behavioral test through the real entry point" },
   { key: "honest", label: "Skipped/inconclusive checks reported explicitly" },

package/lib/code-health/config.mjs

@@ -40,6 +40,19 @@ export const DEFAULT_CONFIG = {
     dependencyRules: { enabled: false, config: ".asf-code-health.rules.mjs" },
   },
 
+  // Model level (P27, references/06j-data-model.md): a tripwire that asks
+  // whether a deletion decision was written down. Built in — no tool to be
+  // missing. The pattern set is illustrative; projects add their own dialect
+  // with extraCascadePatterns rather than waiting for a release.
+  model: {
+    enabled: true,
+    requireDeclaration: true, // cascade requires an asf-model: declaration
+    deleteRebuild: true, // delete + reinsert of the same target
+    declarationWindowLines: 8,
+    rebuildWindowLines: 30,
+    extraCascadePatterns: [],
+  },
+
   ignore: [
     "**/node_modules/**",
     "**/dist/**",
@@ -107,6 +120,7 @@ export function normalizeConfig(raw) {
   const f = isPlainObject(raw.function) ? raw.function : {};
   const m = isPlainObject(raw.module) ? raw.module : {};
   const a = isPlainObject(raw.architecture) ? raw.architecture : {};
+  const md = isPlainObject(raw.model) ? raw.model : {};
   const metric = (obj, name) => (isPlainObject(obj[name]) ? obj[name] : {});
 
   const complexity = metric(f, "complexity");
@@ -153,6 +167,17 @@ export function normalizeConfig(raw) {
         config: typeof depRules.config === "string" && depRules.config ? depRules.config : d.architecture.dependencyRules.config,
       },
     },
+    model: {
+      enabled: bool(md.enabled, d.model.enabled),
+      requireDeclaration: bool(md.requireDeclaration, d.model.requireDeclaration),
+      deleteRebuild: bool(md.deleteRebuild, d.model.deleteRebuild),
+      declarationWindowLines: num(md.declarationWindowLines, d.model.declarationWindowLines),
+      rebuildWindowLines: num(md.rebuildWindowLines, d.model.rebuildWindowLines),
+      extraCascadePatterns:
+        Array.isArray(md.extraCascadePatterns) && md.extraCascadePatterns.length > 0
+          ? md.extraCascadePatterns.filter((x) => typeof x === "string" && x.length > 0)
+          : [],
+    },
     ignore: Array.isArray(raw.ignore) && raw.ignore.every((x) => typeof x === "string") && raw.ignore.length > 0
       ? raw.ignore
       : [...d.ignore],

package/lib/code-health/detect.mjs

@@ -6,6 +6,8 @@
  * are disabled. No IO.
  */
 
+import { hasPersistenceFiles } from "./model.mjs";
+
 /** Languages the gate's metrics understand. */
 export const LANGUAGES = {
   javascript: { name: "JavaScript", exts: [".js", ".jsx", ".mjs", ".cjs"] },
@@ -28,7 +30,7 @@ export function detectLanguages(filePaths) {
 }
 
 /** A metric that the gate can run. */
-export function planMetrics(config, languages, tools) {
+export function planMetrics(config, languages, tools, opts = {}) {
   const plans = [];
   const hasJs = languages.has("javascript") || languages.has("typescript");
   const hasTs = languages.has("typescript");
@@ -87,6 +89,24 @@ export function planMetrics(config, languages, tools) {
     });
   }
 
+  // Model level (P27): built in, so it needs no tool — but it only has
+  // something to say when the project has persistence to inspect.
+  const md = config.model;
+  const persistence = hasPersistenceFiles(opts.files || []);
+  push({
+    key: "modelFindings",
+    level: "model",
+    tool: "asf-model",
+    enabled: md.enabled && persistence,
+    disableReason: md.enabled ? "no persistence files (no .sql, migrations/, models/, entities/)" : "disabled in config",
+    threshold: 0,
+    thresholdLabel: "no undeclared cascade / rebuild-by-delete",
+    toolAvailable: true,
+    toolName: "asf model scan (built in)",
+    compare: "violations",
+    args: { model: md },
+  });
+
   return plans;
 }
 
@@ -115,7 +135,7 @@ export function resolvePlans(plans, languages) {
   const hasJs = languages.has("javascript") || languages.has("typescript");
   const anySource = languages.size > 0;
   return plans.map((p) => {
-    if (!p.enabled) return { ...p, status: "disabled", reason: "disabled in config" };
+    if (!p.enabled) return { ...p, status: "disabled", reason: p.disableReason || "disabled in config" };
     if (p.tool === "eslint" || p.tool === "eslint-sonarjs" || p.tool === "madge") {
       if (!hasJs) return { ...p, status: "skip-lang", reason: "no JS/TS sources" };
     }

package/lib/code-health/index.mjs

@@ -41,8 +41,8 @@ export async function runHealth(projectRoot, args = [], deps = {}) {
   const files = listSourceFiles(projectRoot, config.ignore);
   const languages = detectLanguages(files);
   const tools = deps.tools || detectTools(projectRoot, deps);
-  const plans = resolvePlans(planMetrics(config, languages, tools), languages);
-  const results = await runAll(plans, projectRoot, { ...deps, timeoutMs: config.toolTimeoutSeconds * 1000 });
+  const plans = resolvePlans(planMetrics(config, languages, tools, { files }), languages);
+  const results = await runAll(plans, projectRoot, { ...deps, files, timeoutMs: config.toolTimeoutSeconds * 1000 });
   const rows = plans.map((p) => evaluateRow(p, results[p.key]));
   const v = verdict(rows, config);
 

package/lib/code-health/model.mjs

@@ -0,0 +1,271 @@
+/**
+ * Code Health Gate — model level (P27).
+ *
+ * Two objective fitness functions over persistence code, per
+ * references/06j-data-model.md. Dependency-free: no tool to install, no parser,
+ * no network — a model gate that cannot run never gates.
+ *
+ * **This is a tripwire, not an authority.** It asks one mechanical question —
+ * *is there a deletion decision here that nobody wrote down?* — and it will miss
+ * stores and dialects it has not been told about. That is why the obligation
+ * lives in the DoD checkbox (06b Rule 20) and in the invariant tests (06g §3),
+ * not here. A clean scan is not a pass; it means the tripwire did not catch
+ * anything.
+ *
+ * The pattern set below is deliberately **illustrative, not exhaustive**. The
+ * gate is not "we recognise these six spellings of cascade" — the gate is
+ * "a cascade requires a declaration". Projects add their own dialect with
+ * `model.extraCascadePatterns` rather than waiting for a release (06c Rule 3:
+ * config drives behaviour).
+ *
+ *   undeclared-cascade     a cascade declaration with no ownership declaration
+ *   delete-then-reinsert   rebuild-by-delete over one table/collection
+ *
+ * Both are waivable with `asf-model-accept: <reason>` — greppable, so an accepted
+ * exception stays visible instead of becoming a silent pass.
+ */
+
+/**
+ * Declarations whose documented meaning is "deleting the parent takes the
+ * children". Relational, ORM-mapped and object-store alike — the *concept* is
+ * what matters, not which store expresses it. Extend via config.
+ */
+const CASCADE_DECL_RES = [
+  { marker: "ON DELETE CASCADE", re: /\bON\s+DELETE\s+CASCADE\b/i },
+  { marker: "onDelete: Cascade", re: /\bon_?delete\s*[:=]\s*:?\s*["']?cascade["']?/i },
+  { marker: "on_delete=models.CASCADE", re: /\bon_delete\s*=\s*\w+\.CASCADE\b/ },
+  { marker: "dependent: :destroy", re: /\bdependent\s*(?::|=>)\s*:(?:destroy|delete_all)\b/ },
+  { marker: "cascade remove", re: /\b(?:CascadeType\s*\.\s*(?:REMOVE|ALL)|DeleteBehavior\s*\.\s*Cascade|orphanRemoval\s*=\s*true)\b/ },
+  { marker: 'cascade = "…delete…"', re: /\bcascade\s*=\s*["'][^"']*delete/i },
+];
+
+/** Writes and deletions, matched on verb shape rather than store dialect. */
+const DELETE_VERBS = /^(deleteMany|deleteOne|deleteAll|destroyAll|bulkDelete|delete|remove|removeAll|destroy)$/i;
+const INSERT_VERBS = /^(insertMany|insertOne|createMany|bulkCreate|bulkWrite|insert|insertAll|save|upsert|create)$/i;
+/** Verbs that also exist on in-memory collections — trusted only in store files. */
+const AMBIGUOUS_VERBS = /^(delete|remove|removeAll|destroy|save|upsert|create|insert)$/i;
+
+/** Method calls, matched on the verb; the target is resolved per call. */
+const VERB_RE = /\.([A-Za-z_$][\w$]*)\s*\(/g;
+const SQL_DELETE_RE = /\bDELETE\s+FROM\s+([`"\[]?[\w.]+)/gi;
+const SQL_INSERT_RE = /\bINSERT\s+INTO\s+([`"\[]?[\w.]+)/gi;
+const NAMED_TARGET_RE = /\b(?:collection|from|table|model|entity)\s*\(\s*["']([\w.\-]+)["']/i;
+
+/** What a call at `idx` acts on: a named target, else the receiver's last name. */
+function targetBefore(line, idx) {
+  const before = line.slice(0, idx);
+  const named = NAMED_TARGET_RE.exec(before);
+  if (named) return named[1];
+  let cleaned = before.replace(/\s+$/, "");
+  if (cleaned.endsWith("))")) cleaned = cleaned.replace(/\([^()]*\)$/, "");
+  cleaned = cleaned.replace(/[.(\s]+$/, "");
+  const m = /([A-Za-z_$][\w$]*)$/.exec(cleaned);
+  return m ? m[1] : null;
+}
+
+/** A file that demonstrably talks to a store — needed to trust ambiguous verbs. */
+const PERSISTENCE_SIGNAL_RE =
+  /\b(createTable|CREATE\s+TABLE|migrat|schema|@Entity|@Table|__tablename__|@@model|defineSchema|collection|repository|session|transaction|BEGIN|COMMIT)\b/i;
+
+/** Statements that name a table; used to find the child of a cascade. */
+const SQL_TABLE_RE = /\b(?:ALTER|CREATE|DROP)\s+TABLE\s+(?:IF\s+(?:NOT\s+)?EXISTS\s+)?([`"\[]?[\w.]+)/i;
+const DECL_BLOCK_RE = /^\s*(?:class|model|type|table|collection|resource|entity)\s+["']?([A-Za-z_][\w]*)["']?/im;
+const TABNAME_RE = /__tablename__\s*=\s*["']([\w.]+)["']/i;
+
+/** `asf-model:` declares; `asf-model-accept:` waives. Both stay greppable. */
+const TAG_RE = /asf-model(-accept)?\s*:/i;
+
+const IDENT = (s) =>
+  String(s || "")
+    .replace(/[`"\[\]\s]/g, "")
+    .split(".")
+    .pop()
+    .toLowerCase();
+
+/** Compile project-supplied dialect additions; invalid patterns are dropped. */
+export function extraCascadePatterns(cfg) {
+  const out = [];
+  for (const p of (cfg && cfg.extraCascadePatterns) || []) {
+    if (typeof p !== "string" || !p) continue;
+    try {
+      out.push({ marker: `custom: ${p}`, re: new RegExp(p, "i") });
+    } catch {
+      /* invalid regex — ignore rather than crash the gate */
+    }
+  }
+  return out;
+}
+
+/** Distance in lines to the nearest preceding asf-model tag, or null. */
+export function nearestTag(lines, idx, windowLines) {
+  for (let d = 0; d <= windowLines; d++) {
+    const i = idx - d;
+    if (i < 0) break;
+    const m = TAG_RE.exec(lines[i]);
+    if (m) return { distance: d, accept: Boolean(m[1]) };
+  }
+  return null;
+}
+
+/** The table/collection a cascade at `idx` belongs to (the child, not the parent). */
+export function childTableAt(lines, idx, lookback = 12) {
+  for (let i = idx; i >= Math.max(0, idx - lookback); i--) {
+    const t = SQL_TABLE_RE.exec(lines[i]);
+    if (t) return IDENT(t[1]);
+    const tn = TABNAME_RE.exec(lines[i]);
+    if (tn) return IDENT(tn[1]);
+    const c = DECL_BLOCK_RE.exec(lines[i]);
+    if (c) return IDENT(c[1]);
+  }
+  return null;
+}
+
+/** Text of the statement containing `idx` (SQL: back to ; and forward to ;). */
+export function enclosingStatement(lines, idx, span = 15) {
+  let start = idx;
+  while (start > 0 && !/[;]\s*$/.test(lines[start - 1]) && idx - start < span) start--;
+  let end = idx;
+  while (end < lines.length - 1 && !/[;]\s*$/.test(lines[end]) && end - idx < span) end++;
+  return lines.slice(start, end + 1).join("\n");
+}
+
+/** Delete/insert events, matched on verb shape — no per-store dialect table. */
+function collectEvents(lines, trustedFile) {
+  const deletes = [];
+  const inserts = [];
+  const add = (arr, line, target) => {
+    const t = IDENT(target);
+    if (t && t.length > 1) arr.push({ line, target: t });
+  };
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    for (const m of line.matchAll(SQL_DELETE_RE)) add(deletes, i, m[1]);
+    for (const m of line.matchAll(SQL_INSERT_RE)) add(inserts, i, m[1]);
+
+    VERB_RE.lastIndex = 0;
+    let m;
+    while ((m = VERB_RE.exec(line))) {
+      const verb = m[1];
+      // `map.delete(x)` and `list.remove(x)` are not persistence calls: trust the
+      // ambiguous verbs only where the file demonstrably talks to a store.
+      if (AMBIGUOUS_VERBS.test(verb) && !trustedFile) continue;
+      const target = targetBefore(line, m.index);
+      if (DELETE_VERBS.test(verb)) add(deletes, i, target);
+      else if (INSERT_VERBS.test(verb)) add(inserts, i, target);
+    }
+  }
+  return { deletes, inserts };
+}
+
+/**
+ * Scan one file's text. Pure — no IO. `cfg` is the `model` config block.
+ * Returns findings sorted by line.
+ */
+export function scanModelSource(relPath, text, cfg = {}) {
+  const lines = String(text).split(/\r?\n/);
+  const findings = [];
+  // File-level opt-out lives here so every entry point honours it. It stays
+  // greppable — an opt-out nobody can find is a silent pass.
+  if (/\basf-model-ignore\b/i.test(text)) return findings;
+  const window = cfg.rebuildWindowLines || 30;
+  const tagWindow = cfg.declarationWindowLines || 8;
+  const cascades = [...CASCADE_DECL_RES, ...extraCascadePatterns(cfg)];
+
+  // ── F1: a cascade that nobody declared ───────────────────────────────────
+  if (cfg.requireDeclaration !== false) {
+    for (let i = 0; i < lines.length; i++) {
+      const hit = cascades.find((c) => c.re.test(lines[i]));
+      if (!hit) continue;
+      if (nearestTag(lines, i, tagWindow)) continue;
+      const child = childTableAt(lines, i);
+      findings.push({
+        rule: "undeclared-cascade",
+        file: relPath,
+        line: i + 1,
+        table: child,
+        marker: hit.marker,
+        message: `${hit.marker}${child ? ` on ${child}` : ""} has no ownership declaration — add \`asf-model: ${child || "<child>"} -> <parent> = composition|instance|ledger, owner: <who>\` within ${tagWindow} lines above (06j §2).`,
+      });
+    }
+  }
+
+  // ── F2: rebuild-by-delete over one table/collection ─────────────────────
+  if (cfg.deleteRebuild !== false) {
+    const { deletes, inserts } = collectEvents(lines, PERSISTENCE_SIGNAL_RE.test(text) || PERSISTENCE_PATH_RE.test(relPath));
+    const reported = new Set();
+    for (const d of deletes) {
+      for (const ins of inserts) {
+        if (ins.target !== d.target) continue;
+        if (Math.abs(ins.line - d.line) > window) continue;
+        const key = `${d.target}:${d.line}`;
+        if (reported.has(key)) continue;
+        reported.add(key);
+        if (nearestTag(lines, Math.max(d.line, ins.line), tagWindow)) continue;
+        findings.push({
+          rule: "delete-then-reinsert",
+          file: relPath,
+          line: d.line + 1,
+          table: d.target,
+          marker: "delete + insert",
+          message: `${d.target} is deleted (line ${d.line + 1}) and re-inserted (line ${ins.line + 1}) within ${window} lines — rebuild-by-delete destroys row identity and any state attached to those rows (06j M3). Upsert on a stable identity, or waive with \`asf-model-accept: <reason>\`.`,
+        });
+      }
+    }
+  }
+
+  return findings.sort((a, b) => a.line - b.line || a.rule.localeCompare(b.rule));
+}
+
+/** File names that are persistence-shaped even when the extension is not. */
+const PERSISTENCE_PATH_RE =
+  /(\/|^)(migrations?|alembic|db|dao|repositories?|repos?|models?|entities|stores?|collections?|schema|persistence)\/|\.sql$|\.prisma$/i;
+
+const SQL_EXT_RE = /\.sql$/i;
+/** Schema DSLs are persistence code even though they are not "source". */
+const DSL_EXT_RE = /\.(?:prisma|proto|avsc|edn)$/i;
+const CODE_EXT_RE = /\.(?:js|jsx|mjs|cjs|ts|tsx|mts|cts|py|rb|php|java|kt|cs|go|rs|ex|exs|scala)$/i;
+
+/** Which of the listed files should the model level look at? */
+export function isModelRelevant(relPath) {
+  return SQL_EXT_RE.test(relPath) || DSL_EXT_RE.test(relPath) || CODE_EXT_RE.test(relPath);
+}
+
+/**
+ * Does the project have anything for this level to inspect? Name-based, so a
+ * project whose persistence layer sits somewhere unusual sees `scanned: 0` in
+ * the report rather than a silent pass — say so in the delivery report.
+ */
+export function hasPersistenceFiles(files) {
+  return (files || []).some((f) => SQL_EXT_RE.test(f) || DSL_EXT_RE.test(f) || PERSISTENCE_PATH_RE.test(f));
+}
+
+/**
+ * Scan a project. `files` and `readFile` are injectable for tests.
+ * Returns { findings, scanned, errors }.
+ */
+export async function scanModel(root, { files, readFile, config } = {}) {
+  const fs = readFile || (await import("node:fs/promises")).readFile;
+  const list = files || (await import("./run.mjs")).listSourceFiles(root, null);
+  const findings = [];
+  const errors = [];
+  let scanned = 0;
+
+  for (const rel of list) {
+    if (!isModelRelevant(rel)) continue;
+    let text;
+    try {
+      text = await fs(`${root}/${rel}`, "utf-8");
+    } catch (err) {
+      errors.push(`${rel}: ${err.message}`);
+      continue;
+    }
+    if (/\basf-model-ignore\b/i.test(text)) continue; // file-level opt-out, greppable
+    scanned++;
+    findings.push(...scanModelSource(rel, text, config));
+  }
+
+  return { findings, scanned, errors };
+}
+
+export const MODEL_RULES = ["undeclared-cascade", "delete-then-reinsert"];

package/lib/code-health/report.mjs

@@ -29,7 +29,7 @@ export function evaluateRow(plan, result) {
     : compare === "violations"
       ? value > 0
       : value > plan.threshold;
-  return {
+  const row = {
     key: plan.key,
     level: plan.level,
     value: formatValue(plan.key, value),
@@ -37,12 +37,19 @@ export function evaluateRow(plan, result) {
     status: failed ? "fail" : "pass",
     reason: failed ? `value ${value} exceeds ${plan.thresholdLabel}` : "",
   };
+  // Model findings carry the concrete file:line and the fix, so the agent can
+  // act on the report instead of guessing what tripped it (06b Rule 4).
+  if (result && Array.isArray(result.findings) && result.findings.length > 0) {
+    row.details = result.findings.map((f) => `${f.file}:${f.line}  ${f.rule} — ${f.message}`);
+  }
+  return row;
 }
 
 function formatValue(key, value) {
   if (value === null || value === undefined) return "?";
   if (key === "duplication") return `${value}%`;
   if (key === "circularDependencies") return `${value} cycle(s)`;
+  if (key === "modelFindings") return `${value} finding(s)`;
   return String(value);
 }
 
@@ -79,6 +86,11 @@ export function formatReport(rows, config) {
       row.status === "error" ? "!" :
       row.status === "skipped" ? "–" : "·";
     lines.push(`${mark} ${row.level.padEnd(12)} ${row.key.padEnd(22)} ${String(row.value).padEnd(10)} ${row.threshold}${row.reason ? "  (" + row.reason + ")" : ""}`);
+    if (Array.isArray(row.details) && row.details.length > 0) {
+      const shown = row.details.slice(0, 12);
+      for (const d of shown) lines.push(`      ${d}`);
+      if (row.details.length > shown.length) lines.push(`      … ${row.details.length - shown.length} more`);
+    }
   }
   const v = verdict(rows, config);
   lines.push("──────────────────────");
@@ -106,6 +118,7 @@ export function jsonReport(rows, config) {
       threshold: r.threshold,
       status: r.status,
       reason: r.reason || "",
+      details: r.details || [],
     })),
     verdict: config.enabled ? verdict(rows, config) : { healthy: true, failures: 0, errors: 0, skipped: 0, ran: 0 },
   };

package/lib/code-health/run.mjs

@@ -8,6 +8,7 @@
 import { readdirSync, statSync, existsSync } from "node:fs";
 import { join, relative, sep } from "node:path";
 import { spawn } from "node:child_process";
+import { scanModel } from "./model.mjs";
 
 /** Run a command with a hard timeout; resolve on exit. */
 export function exec(cmd, args, { cwd, timeoutMs = 120_000, env } = {}) {
@@ -191,6 +192,20 @@ export async function runDepcruise(plan, root, { execFn = exec, timeoutMs = 120_
   return { value: res.code === 0 ? 0 : 1 };
 }
 
+/**
+ * Run the model level (P27). Built in: no spawn, no tool to be missing. Any
+ * finding fails the level unless waived in-source with `asf-model-accept:`.
+ */
+export async function runModelScan(plan, root, opts = {}) {
+  const res = await scanModel(root, { files: opts.files, readFile: opts.readFile, config: plan.args.model });
+  return {
+    value: res.findings.length,
+    findings: res.findings,
+    scanned: res.scanned,
+    error: res.errors.length ? `unreadable file(s): ${res.errors.join("; ")}` : undefined,
+  };
+}
+
 /** Run all plans; returns key → result. */
 export async function runAll(plans, root, opts = {}) {
   const results = {};
@@ -208,6 +223,7 @@ export async function runAll(plans, root, opts = {}) {
     if (p.tool === "jscpd") results[p.key] = await runJscpd(p, root, opts);
     else if (p.tool === "madge") results[p.key] = await runMadge(p, root, opts);
     else if (p.tool === "dependency-cruiser") results[p.key] = await runDepcruise(p, root, opts);
+    else if (p.tool === "asf-model") results[p.key] = await runModelScan(p, root, opts);
   }
   return results;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-aia-asf",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "description": "Ai Applied Agentic Software Factory — codifies the full software development flow: intake, research, spec capture, adversarial analysis, planning with approval gates, test-first implementation, and release. Requires pi-vigilant, pi-smart-web-search, pi-smart-fetch, and pi-aia-browser.",
   "keywords": [
     "pi-package",

package/skills/aia-asf/SKILL.md

@@ -236,6 +236,7 @@ Execute the task list milestone by milestone. Discipline rules:
 9. **Challenge approved designs (M4)**: if a spec's literal reading creates product tension (e.g. feedback clusters under "Plan" when "Plan = plans"), stop and resolve it with the user before implementing — never implement blindly and call it delivered.
 10. **Trace before claiming delivered (M5)**: the delivery log is a claim; the code is the evidence. Before marking anything ✅, trace the actual code path, confirm the output is consumed by a surface, and confirm the operator-facing outcome test passes.
 11. **No stubs, no fake data, no invented facts (`references/06i-completeness.md`)**: the deliverable is the real implementation. Finish it, or state the discrepancy plainly to the user — what is missing, why, what remains. Never let the user discover the gap by using the product.
+12. **The model is asserted, not assumed — for any change that WRITES to a store (06b Rule 20 / `references/06j-data-model.md`)**: the trigger is what the change writes, not where the diff lives — "only a backend change" is the case that needs it most. Declare ownership for every relationship touched (composition / instance / ledger, owner, survives-parent), and test the **non-effect**: seed the referencing rows with production-shaped data and assert they survive, and assert the tables the change does not name are unchanged (06g §3). Run `/asf health` and resolve or accept its findings. **Uncertain whether the model is touched? Then it is touched.** A green suite is not evidence here — the table a cascade empties is usually never populated by the suite that stayed green. **Capture the obligations as MUST specs (`capture_spec`)** so the loop guard verifies them at settle as it verifies any specification from any source — the guard checks completion, it does not know what a cascade is and must not have to.
 
 ---
 
@@ -249,6 +250,13 @@ Also check the **stability DoD** (`references/06f-stability.md`): if the deliver
 
 Also check the **completeness DoD** (`references/06i-completeness.md`): no stub, placeholder, unimplemented path or fabricated data left on a user-reachable path (or declared to the user with the reason); every part of the ask reachable from where the user enters it, with the exercising command/request/action named in the delivery report; nothing asked for quietly moved to "later"; no claim presented as verified when it was not. `pi-vigilant` scans the changed files for these markers at completion — resolve every finding or explain it; a clean scan is not proof of completeness.
 
+Also check the **model DoD** (`references/06j-data-model.md`) when the change
+writes to a store: every relationship touched has a written ownership
+declaration, the invariant and non-effect tests (06g §3) exist and are green,
+and `/asf health`'s model level passes or its findings are accepted with a
+reason. State the scan result honestly — `scanned: 0` means it looked at
+nothing, and that is said out loud, never reported as a pass.
+
 **Large work:** run `/asf verify` — it mechanically validates the **spec-to-code traceability matrix** (M1): every `met` spec must carry `trace` (outcome → codePath → testFile + assertion), testFile must exist, assertion must appear in it. FAIL rows block delivery. **Verify ingested specs from external planning docs too** — the doc's ✅ markers are claims, not evidence.
 
 **Independent reviewer gate (large work, P19):** before delivery, run the
@@ -285,6 +293,10 @@ conflicts). Record the review + triage in the delivery report.
 - ❌ Deferring browser verification of a touched interface to final verification — open it in the build, before committing that change (06b Rule 9)
 - ❌ "It's only a backend change" with no render path named — if uncertain whether it reaches a surface, browser-test it (06b Rule 9)
 - ❌ Reporting "browser tested" without the page, action and assertion — that is an assertion, not evidence; and a missing browser tool must be said out loud, never read as passed (06b Rule 9)
+- ❌ A green suite that never populated the table the change destroys — asserting only the intended effect is not evidence about the model (06j, 06g §3)
+- ❌ `CASCADE` / delete-and-reinsert chosen because the store defaulted to it or the file above does it — a default and a precedent are both non-decisions (06j M1, M4)
+- ❌ Reporting a clean model scan as a passed check when the level scanned nothing, or trusting the scan where the store exposes no constraints to inspect — the scan is a tripwire; the invariant tests are the gate (06j §5)
+- ❌ Treating the model gate as about "projects that have a database schema" — the trigger is whether **this change writes to a store**, in any store (06b Rule 20)
 - ❌ Vague commits or CHANGELOG placeholders
 - ❌ Declaring done while specs are still `open`
 - ❌ Publishing anything beyond the configured release policy — no `.asf-release.json` means the default: always get the user's explicit go-ahead
@@ -341,17 +353,18 @@ reads at most 06b + 06c; large work reads the ones its phase calls for.
 |---|---|---|
 | `01-intake.md` | question bank, probing, external planning docs (M6) | Phase 1 (large) |
 | `02-research.md` | research playbook, search templates | Phase 2 (large) |
-| `04-adversarial.md` | adversarial checklist (spec/architecture/security lenses) | Phase 4 (large) |
-| `05-plan.md` | PLAN.md template + ADRs + quality scenarios + ATAM-lite + views | Phase 5 (large) |
+| `04-adversarial.md` | adversarial checklist (spec/architecture/data-model/security lenses) | Phase 4 (large) |
+| `05-plan.md` | PLAN.md template + ADRs + quality scenarios + ATAM-lite + views + ownership table | Phase 5 (large) |
 | `06-implementation.md` | coding discipline, M4/M5, drift self-correction (P20) | Phase 6 |
-| `06b-testing-qa.md` | **mandatory** testing & QA standard (19 rules + DoD) | before writing tests (always) |
+| `06b-testing-qa.md` | **mandatory** testing & QA standard (20 rules + DoD) | before writing tests (always) |
 | `06c-code-quality.md` | **mandatory** modularity standard (9 rules, deep modules, smells) | before structuring code |
 | `06d-delegation.md` | intercom & subagents + independent reviewer gate (P19) | before delegating; Phase 7 review (large) |
-| `06e-code-health.md` | Code Health Gate (+ depth, supply-chain, secrets metrics) | Gate 8 (large) |
+| `06e-code-health.md` | Code Health Gate (+ depth, supply-chain, secrets, model metrics) | Gate 8 (large) |
 | `06f-stability.md` | stability patterns + error handling + observability (P06/P07/P08) | **if the deliverable makes external calls or is a service** |
-| `06g-test-design.md` | risk-based test derivation + determinism | Phase 6 large (test plan) / non-trivial tests |
+| `06g-test-design.md` | risk-based test derivation + determinism + invariant/non-effect tests (P27) | Phase 6 large (test plan) / non-trivial tests |
 | `06h-security.md` | threat model, ASVS DoD, supply chain, agent tools | Phase 4/5 large; small = one line |
 | `06i-completeness.md` | **mandatory** no stubs / no fabricated data / no invented facts + completeness DoD | before implementing and before claiming done (always) |
+| `06j-data-model.md` | **mandatory when the work writes to a store** — ownership classes, model rules M1-M8, legitimate exceptions, invariant/non-effect tests + model DoD | before implementing any store write, and before claiming done |
 | `07-release.md` | release workflow + **configurable release policy** (`.asf-release.json`: when/how) + test-on-publish | before publishing |
 
 ## ASF self-modification policy (P22)

package/skills/aia-asf/references/04-adversarial.md

@@ -52,6 +52,25 @@ Challenge every spec and design decision like a hostile reviewer. For each item,
 - **Rollback**: if this ships and breaks, how do we revert?
 - **Observability**: logs, metrics, errors — can we see it working in production?
 
+## Data & model questions (P27 — when the work touches persistence)
+
+The code and the behaviour get reviewed; the model usually does not, and a model
+defect is invisible to every behavioural test (full rules in
+[06j-data-model.md](06j-data-model.md)). For every entity the change touches:
+
+- **Ownership**: who creates this row, who may delete it, and does it survive its
+  parent? If nobody can answer, that is the finding.
+- **Fan-out**: what else points at this row, and what happens to those rows when
+  it is deleted — by a constraint, by an ORM mapping, or by a loop someone wrote?
+- **Identity**: what makes two rows the same thing, and does anything enforce it?
+- **Invariants**: what must *always* be true of this data, and is it enforced
+  somewhere that cannot be bypassed, or only asserted in a handler?
+- **Non-effects**: which tables/collections must be unchanged by this operation —
+  and does any test look at them?
+
+"The suite is green" is not an answer to any of these; the suite almost certainly
+never populated the table in question.
+
 ## Resolution rules
 
 - Finding → **new spec** (capture_spec) or **spec change** (capture superseding spec; old one becomes obsolete)
@@ -61,3 +80,6 @@ Challenge every spec and design decision like a hostile reviewer. For each item,
 ## Adversarial gate
 
 Summarize: findings found, specs added/changed, risks accepted → user confirmation.
+For persistence work, the summary states the ownership answers found missing
+(06j) — an unanswered ownership question is a finding like any other, not a
+detail to discover during implementation.

package/skills/aia-asf/references/05-plan.md

@@ -73,13 +73,33 @@ its own sake — the Architecture/Design prose is the primary artifact.
 
 ## Architecture / Design
 - Modules and their responsibilities (small, single-purpose — see `references/06c-code-quality.md`)
-- Data model / schema (if any)
+- Data model / schema (if any) — expanded in the next section when the work
+touches persistence
 - Key flows (request lifecycle, event flow)
 - Interfaces / contracts between components
 - **Where shared truth lives** (single source of truth map: which module owns each shared capability)
 - **Layering**: one-way dependency rules between layers; what each layer may/may not import
 - **Standalone testability**: how each module is exercised outside the host with the same calls
 
+## Data model & ownership (P27 — when the work touches persistence)
+
+The artifact the model gate reads. One row per relationship the change touches;
+if you cannot fill a row, that is a finding for Phase 4, not a blank to skip
+(full rules in `references/06j-data-model.md`).
+
+| Relationship | Class | Owner | Survives parent? | Delete semantics | Enforced by |
+|---|---|---|---|---|---|
+| `org_action_items → checklist_questions` | instance | the organisation | **yes** | `SET NULL` + detach-and-keep | FK + invariant test |
+| `checklist_steps → checklist_templates` | composition | the template version | no | `CASCADE` | FK + `asf-model:` tag |
+
+Also state, for the change as a whole:
+
+- **Identity**: what makes two rows the same thing, and what enforces it.
+- **Invariants** that must always hold, and where each is enforced (constraint vs
+  handler — a handler assertion is a claim, a constraint is a guarantee).
+- **Invariant / non-effect tests** that will prove it (06g §3), listed by name.
+- `n/a: no persistence touched, because <reason>` when it genuinely does not apply.
+
 ## Spec-to-code traceability matrix
 For every spec, the operator-facing outcome, the code path that delivers it, and the test that asserts it. This is what `/asf verify` checks mechanically at delivery (M1).
 

package/skills/aia-asf/references/06-implementation.md

@@ -24,6 +24,11 @@
    `pi-aia-browser` **before committing that change** (06b Rule 9) — not at
    final verification. If you cannot argue the change provably cannot reach a
    rendered surface, it counts as touched and gets a browser run.
+6. Assert the **model** before committing a change that writes to a store
+   (06b Rule 20 / 06j): write the ownership declaration for each relationship
+   touched, and the invariant + non-effect test (06g §3) that fails until the
+   model is right — then run `/asf health` and resolve or accept its findings.
+   Do this while the change is one edit wide, not at final verification.
 
 For web interfaces, browser tests via pi-aia-browser are part of the test suite, not an afterthought.
 
@@ -124,6 +129,11 @@ are drifting):
   browser verification).
 - **Quality drift** — accepting a shortcut that changes behavior or leaves
   dead machinery, then marking it delivered (M5).
+- **Model drift** — extending a destructive persistence pattern because the
+  surrounding code already does it: inheriting a cascade, or writing another
+  delete-and-reinsert "like the handler above". The file doing it first is not
+  a justification; it is an unreviewed model you are now compounding. Stop and
+  resolve it (06j), even when the ask would be satisfied by copying it.
 
 **Self-correction loop (autonomous, no user needed):**
 

package/skills/aia-asf/references/06b-testing-qa.md

@@ -194,6 +194,7 @@ never arrives, the wiring is dead — that is a failed test.
 - [ ] **Delivery report complete (P14): every spec with status + evidence, every test run with result, every skipped/inconclusive check listed with reason, and the not-tested register (what was deliberately not tested and why)**
 - [ ] **Stability line (06f): if the deliverable makes external calls, it has timeouts and bounded retries (idempotent only)**
 - [ ] **Security line (06h): no secrets in the repo; no untrusted input reaches a shell/query/path unvalidated; no unbounded resource use on user-controlled input**
+- [ ] **Model line (06j): every relationship the change touches carries a written ownership declaration; store writes have invariant and non-effect tests (06g §3); `/asf health` model level passes or its findings are accepted with a reason — `n/a: no persistence touched, because <reason>` otherwise**
 
 ## Rule 11 — Report honestly
 
@@ -417,3 +418,35 @@ This does not change Rule 10, Rule 11, or the commit-gate workflow: a project
 that commits after every green run already runs full before every commit, so
 Rule 19 only ever saves the intermediate runs inside a single change — it
 never reduces what runs before anything is committed.
+
+## Rule 20 — The model is asserted, not assumed (P27)
+
+**The trigger is what the change WRITES, not where the diff lives.** Any change
+that writes to a store — relational, document, key-value, queue, object store, or
+a file another component reads — goes through
+[06j-data-model.md](06j-data-model.md). A diff that only touches `src/server/`
+is not exempt; the model *is* the backend.
+
+Three obligations, and each has a mechanical counterpart because prose alone is
+something an agent can satisfy by nodding:
+
+1. **Declare ownership** for every relationship touched: class
+   (composition / instance / ledger), owner, and whether the child survives its
+   parent (06j §2). No declaration is not a neutral state — it means the
+   relationship was never reviewed.
+2. **Test the non-effect**, not only the intended effect (06g §3): seed the
+   referencing rows with production-shaped data and assert they survive; assert
+   the tables the change does not name are unchanged. A suite that never
+   populated the destroyed table cannot see the destruction.
+3. **Run the scan** — `/asf health` model level. It is a tripwire, not an
+   authority: pattern-shaped and store-shaped, so a clean scan means it caught
+   nothing. If it reports `scanned: 0`, say so; never let a scan you did not run
+   or that saw nothing read as a passed check.
+
+**When uncertain whether the model is touched, it is touched** — the same
+inversion as Rule 9 and Rule 19. "It's only a backend change" is not an argument.
+
+**Evidence, not assertion.** The delivery report names the declarations written,
+the invariant tests added, and the scan result. A bare "model reviewed" is not
+evidence. An accepted finding (`asf-model-accept: <reason>`) is a decision you
+show, not a pass you claim.

package/skills/aia-asf/references/06e-code-health.md

@@ -27,6 +27,7 @@ Three levels, each with objective thresholds (all configurable):
 | design | module depth (interface vs implementation) | report-only heuristic | report-only (never gates) |
 | supply chain | dependency vulnerabilities | npm audit / osv-scanner | warn (high/critical fails) |
 | secrets | secrets in repo | gitleaks | warn (any finding fails) |
+| model | undeclared cascade / rebuild-by-delete | built-in scan (P27) | any finding fails |
 
 **Depth metric (P05, report-only):** a heuristic that flags **shallow
 pass-through modules** — modules whose interface is nearly as large as their
@@ -40,6 +41,16 @@ for small work; for large work a high/critical vulnerability in a runtime
 dependency or any secret finding blocks delivery. See
 `references/06h-security.md` for the full rules.
 
+**Model level (P27):** two objective fitness functions over persistence code —
+a cascade with no ownership declaration, and the delete-then-reinsert signature.
+Built in (no tool to install, so it can never be skipped for a missing
+dependency), and it reports the concrete `file:line` and the fix. It is a
+**tripwire, not an authority**: the pattern set is illustrative and
+store-agnostic in principle, so a clean scan means it caught nothing, not that
+the model is sound — the obligation sits in the DoD (06b Rule 20) and the
+invariant tests (06g §3). Full rules in
+[06j-data-model.md](06j-data-model.md).
+
 Metrics for languages the project does not use are silently skipped. Metrics
 whose tool is not installed are skipped (or fail the gate when
 `missingTool: "fail"`).
@@ -83,6 +94,14 @@ switched on/off independently.
   "architecture": {
     "dependencyRules": { "enabled": false, "config": ".asf-code-health.rules.mjs" }
   },
+  "model": {
+    "enabled": true,
+    "requireDeclaration": true,
+    "deleteRebuild": true,
+    "declarationWindowLines": 8,
+    "rebuildWindowLines": 30,
+    "extraCascadePatterns": []
+  },
   "supplyChain": {
     "npmAudit": { "enabled": true, "failOn": "high" },
     "osvScanner": { "enabled": false }

package/skills/aia-asf/references/06g-test-design.md

@@ -70,10 +70,45 @@ immediately; never "re-run into green" (06b Rule 11).
 **DoD line:** *"the suite is deterministic: no flaky test is tolerated; a
 flaky test is fixed or deleted, never retried into green."*
 
-## 3. Where this applies in ASF
+## 3. Invariant and non-effect tests (P27)
+
+Every other rule in this file asks *did the thing you wanted happen?* For
+persistence work that question is not enough, because a model defect is exactly
+an unintended effect on something outside the specification. The suite that let
+327 action items vanish was green: the template saved, the response was 200, and
+the table that emptied was never populated nor inspected.
+
+For any change that writes to a store, add the tests that ask *what must not
+have happened*:
+
+1. **Survival test.** Seed the rows that reference what you are editing or
+   deleting — with **production-shaped data**, because a cascade only fires when
+   the rows exist — and assert they survive. If the child is an instance (06j
+   §1), this test is the executable form of that decision.
+2. **Non-effect assertion.** Snapshot the row/document counts of every table or
+   collection the change does *not* name, and assert they are unchanged. One
+   helper, applies to every write path, and it catches the whole class rather
+   than the one case you imagined.
+3. **Zero-row invariant.** Write the invariant as a query that must return
+   nothing (orphans, duplicates on the business identity, a completed row with no
+   completion time) and run it in the suite. Objective, store-agnostic, and it
+   documents the rule as code.
+4. **Two-user authorization test.** Two identities, objects owned by each, and
+   every operation attempted across the boundary — read, update, delete, export,
+   admin. A UUID is not an authorization check.
+
+These are the hard gate for any store that exposes no constraints to scan
+(06j §5) — where there is no schema to inspect, the invariant test is the only
+thing that can tell you the model is wrong.
+
+**DoD line:** *"for every store write the change introduces, the suite asserts
+what must NOT change, not only what should."*
+
+## 4. Where this applies in ASF
 
 - **Phase 5 (PLAN.md):** the test plan states the risk-derived test list
-  (which risks, which techniques, which tests).
+  (which risks, which techniques, which tests), and names the invariant and
+  non-effect tests for any store write (§3).
 - **Phase 6 (implementation):** write tests with the technique that matches
   the shape; keep them deterministic per the rules above.
 - **Phase 7 (verification):** a flaky test blocks delivery (it is a defect).
@@ -86,3 +121,5 @@ flaky test is fixed or deleted, never retried into green."*
 - ❌ Real network calls inside unit tests
 - ❌ Re-running a flaky test until it passes
 - ❌ Tests that pass only on the developer's machine (locale/timezone)
+- ❌ A green suite that never populated the table the change destroys (06j)
+- ❌ Asserting only the intended effect, never the non-effect (06j)

package/skills/aia-asf/references/06j-data-model.md

@@ -0,0 +1,257 @@
+# 06j — The Data Model Gate
+
+**Status: mandatory for large work (gate blocks), advisory for small work.**
+
+The model is a design artifact and it must be reviewed as one. **Code review is
+not model review.** Everything else in the ASF inspects code (06c, 06e),
+behaviour (06b, 06g), resilience (06f), security posture (06h) or completeness
+(06i) — and a model defect is none of those. It is a wrong assumption about what
+entities exist, who owns them, what must always be true of them, and what may
+happen to them.
+
+This reference exists because a gate set that verifies only *intended effects*
+cannot see a model defect: a model defect **is** an unintended effect on
+something outside the specification. The case that produced it: an admin
+unticked one checkbox on a template and saved; the endpoint rebuilt the
+template by deleting its questions; `ON DELETE CASCADE` took every organisation's
+generated action items with them; the suite was green, because the suite never
+created a single action item. See
+[docs/research/model-blind-spots.md](../../../docs/research/model-blind-spots.md).
+
+**When this applies:** any change that **writes to a store** — schema, migrations,
+ORM/entity definitions, repositories, or a handler that persists. The trigger is
+what the change WRITES, not where the diff lives; if your diff touches none of
+those, say `n/a: no persistence touched, because <reason>` and move on.
+"If it's only a backend change" is not an argument — the model *is* the backend.
+Same inversion as Rule 19 and Rule 9: **when uncertain whether the model is
+touched, it is touched.**
+
+## 1. Ownership classes — the vocabulary that was missing
+
+Every relationship you touch gets classified. The class decides the delete
+semantics; the reason nobody got this wrong *on purpose* is that nobody was
+ever asked.
+
+| Class | The child is… | Delete semantics | Example |
+|---|---|---|---|
+| **composition** | nothing without the parent; exists only as part of it | `CASCADE` legitimate | a step row belonging to one template version |
+| **instance** | a **fact about someone else** that merely cites the parent | **never `CASCADE`** — `SET NULL` / `RESTRICT`, detach-and-keep | an action item an organisation generated *from* a template |
+| **ledger** | a record of something that happened; correctness forbids erasure | **hard delete forbidden** — void / compensate / append | payment, completion, status change, audit entry |
+| **unclassified** | you have not decided | treat as **instance** | — |
+
+The fail-safe default is the expensive direction: an undeclared relationship is
+an *instance*, so `CASCADE` is not available to you until you argue for it. This
+is deliberate. Rebuild-by-delete is not written by people who think cascades are
+wrong; it is written because it is the shortest code path that syncs rows —
+what the literature calls designing for *compositional convenience*. A rule that
+only says "don't" loses to convenience; the default has to be the safe side.
+
+**The test for instance vs composition is one question:** *if the parent is
+deleted, must this row still exist?* If the answer is "the customer's data would
+be wrong without it", it is an instance and the cascade is a bug you have not
+found yet.
+
+## 2. The ownership declaration (the required artifact)
+
+Every relationship touched by the change gets a declaration — in the migration
+or schema file, next to the constraint, and in the plan's data-model section:
+
+```sql
+-- asf-model: org_action_items -> checklist_questions = instance
+--   owner: the organisation; survives template edits; FK is SET NULL.
+ALTER TABLE org_action_items
+  ADD CONSTRAINT fk_item_question FOREIGN KEY (question_id)
+  REFERENCES checklist_questions (id) ON DELETE SET NULL;
+```
+
+Whatever your store or ORM calls it — a FK action, a relation option, a mapping
+attribute, a delete dependency — the declaration is the same three facts: the
+class, the owner, the survival answer.
+
+Rules about the artifact:
+
+- **No declaration ⇒ not reviewed ⇒ not done.** Absence is not neutral. This is
+  the same mechanism as Rule 19's impact statement: "certain" that is not
+  written down is a feeling.
+- `ON DELETE CASCADE` (or `dependent: :destroy`, `onDelete: "cascade"`,
+  `on_delete="CASCADE"`) **requires** a declaration naming the owner and saying
+  why the child is composition. If you cannot write that sentence, the child is
+  an instance.
+- A deliberate exception uses `asf-model-accept: <reason>` — a non-empty reason,
+  on the same or the line above. That is the only way to pass the gate with a
+  finding open, and it is greppable, so an accepted exception stays visible.
+  Silence is never a waiver.
+- **The value is forcing the decision, not the answer.** A declaration that
+  concludes "`CASCADE` is correct here" is a pass, not a failure. What the gate
+  refuses is that nobody was asked.
+
+## 3. Model rules
+
+**M1 — Every relationship has a named owner and a survival answer.** Per
+relationship touched: who creates the child, who may delete it, does it survive
+its parent, and why. Unclassified means instance (§1).
+
+**M2 — Never `CASCADE` from a business fact to a configuration row.** Deleting a
+template, a setting, a catalogue entry or a plan must not delete artefacts a
+human or an organisation produced. `SET NULL`, `RESTRICT`, or detach-and-keep.
+If the child carries an owner (an org, tenant, user or account reference) or
+human-authored state (`title`, `status`, `completed_at`, `amount`), assume
+instance and make the argument explicitly.
+
+**M3 — No rebuild-by-delete where the child has inbound references or
+row-attached state.** "Delete all the children, insert them again" destroys row
+identity, breaks anything pointing at those rows, and silently loses state that
+lives on the row (`completed_at`, status history, counters, attachments). Upsert
+on a **stable identity** instead. Note what the fix in the originating incident
+was: reattach by `question_number` — i.e. *give the row an identity that
+survives a rebuild*. If you are about to write delete-then-insert in one
+transaction, stop; the gate has a fitness function for exactly this shape.
+
+**M4 — Invariants the database can express, live in the database.** Unique,
+not-null, foreign-key and check constraints are enforced by a layer that cannot
+forget, be bypassed by a script, or be missed by a new join. Application-level
+validation is a *claim*; a constraint is a *guarantee*, and it is the only
+guarantee that holds for the caller who reaches the table directly. "There's no
+compiler error for *you forgot `WHERE tenant_id`*" — so put the boundary where
+forgetting is impossible (constraint, RLS policy, scoped accessor), not in
+discipline.
+
+**M5 — If the business says two rows cannot be the same thing, something must
+enforce that.** A unique constraint (scoped to live rows where tombstones
+exist), not a dedupe in a handler and certainly not a dedupe in a recovery
+script. State the identity rule before you implement the write path.
+
+**M6 — Reference across aggregates by identity, and change one aggregate per
+transaction.** A direct reference into another aggregate is an invitation to
+modify both in one commit. If you do not hold the reference, you cannot
+accidentally cascade through it. Where two aggregates must agree, do it through
+an explicit follow-up operation, not through a shared transaction.
+
+**M7 — Destructive lifecycle is a designed subsystem.** For each relationship
+where deletion is possible, decide *which* of these it is: cascade, block until
+empty, detach-and-keep, tombstone, or void-and-append. Then:
+
+- **Restore is an operation with checks**, not a timestamp flip — cascades fired,
+  unique keys were reused, downstream systems reacted.
+- Retention and purge are decided, not drifted into.
+- Deletion propagates as an event to anything that caches or indexes it.
+- Blocking is a legitimate answer. "You cannot delete the template while 327
+  organisations have items generated from it" is a fine product behaviour and a
+  much better default than discovering the answer in production.
+
+**M8 — A wrong-but-plausible empty result must be loud.** A filter that matches
+nothing — missing tenant context, wrong date, a forgotten tombstone predicate —
+returns *success with no rows*, which reads as an empty day and not as a defect.
+Instrument the boundary itself: log when the enforcement context is missing, and
+alert on that pattern. Turning a silent failure mode into a noisy one is a design
+requirement, not observability polish.
+
+## 4. Legitimate exceptions — declared, never silent
+
+Like 06i, the rule is not "never deviate", it is "never deviate quietly". Each
+of these is legitimate **when written down**:
+
+- A genuine composition where `CASCADE` is right (declare the owner).
+- A rebuild-by-delete on a table with no inbound references and no row-attached
+  state (say which table, and why both are absent).
+- Application-level validation instead of a constraint, where the rule spans
+  tables or needs the request context (say why the DB cannot express it).
+- A hard delete required by law, with the anonymise-plus-tombstone shape
+  described in the research notes.
+- An `asf-model-accept:` for a legacy constraint you are not changing in this
+  ticket — with the reason and, ideally, the ticket that will.
+
+What is never legitimate: an undeclared cascade, an unclassified relationship, a
+rebuild-by-delete nobody justified, or a scan finding read back as a clean
+deliverable. **A model finding you chose to accept is a decision; a model
+finding you did not look at is a hole.**
+
+## 5. Prove it is real (Phase 7)
+
+Two mechanisms, and both must run — the prose catches what the machine cannot
+judge, the machine catches what the prose can be talked around.
+
+**Objective fitness functions** — `/asf health` runs the `model` level
+([06e-code-health.md](06e-code-health.md)). Built in, deterministic, no external
+tool. It fails on a cascade with no ownership declaration, and on the
+delete-then-reinsert signature over one table or collection. Objectivity is the
+requirement: "is this ownership correct?" is judgment and stays in review, while
+"does this file declare a cascade with no `asf-model:` tag?" is measurable.
+
+**It is a tripwire, not an authority — and it is store-agnostic by design.** The
+defect is not SQL-shaped: an instance inheriting its parent's lifecycle happens
+in a relational FK action, in an ORM mapping attribute, in a document store's
+delete dependency, in a key-value prefix wipe, or in a loop someone wrote to
+delete children by hand. The scan recognises a small illustrative set of those
+spellings and a project adds its own dialect with `model.extraCascadePatterns`
+rather than waiting for a release. **Where the store has no constraint to
+inspect, the scan has nothing to attach to and the invariant tests below are the
+only hard gate** — say which of the two you relied on, and if the scan reported
+`scanned: 0`, say that too. A clean scan means the tripwire caught nothing, not
+that the model is sound.
+
+**Invariant and non-effect tests** — [06g-test-design.md](06g-test-design.md) §3:
+survival tests, non-effect assertions, zero-row invariant queries, two-user
+authorization tests. These are what a model rule looks like when it stops being
+an opinion, and they are the part that works against any store.
+
+## 6. Definition of Done — model
+
+- [ ] Every relationship the change touches is classified (composition /
+      instance / ledger) with a named owner and a survival answer.
+- [ ] Every `CASCADE` in the diff is declared as a composition, or carries
+      `asf-model-accept:` with a reason.
+- [ ] No rebuild-by-delete over rows with inbound references or row-attached
+      state, or it is declared with why both are absent.
+- [ ] Business invariants the DB can express are constraints, not handler code.
+- [ ] Identity rule stated and enforced where the business says rows cannot
+      duplicate.
+- [ ] Deletion semantics decided per relationship (§M7), including restore.
+- [ ] `/asf health` `model` level passes, or every finding is accepted with a
+      reason and shown; if the level scanned nothing, that is said out loud.
+- [ ] Invariant and non-effect tests exist for the touched relationships
+      (06g §3) and are green — and they are the gate, not the scan, where the
+      store exposes no constraints.
+- [ ] Or: `n/a: no persistence touched, because <reason>`.
+
+## 7. Who enforces this
+
+ASF states the obligation; the loop guard enforces completion **generically**.
+When a change touches persistence, capture the model obligations as MUST specs
+(`capture_spec`) — the ownership decision per relationship, the invariant and
+non-effect tests, the scan result — and mark each `met` with evidence, not
+assertion. The guard then verifies those specs at settle exactly as it verifies
+any specification that arrives from any source, and refuses "done" while a MUST
+spec is open.
+
+Keep model knowledge on this side of the boundary. The guard does not know what
+a cascade is, does not look at schemas, and must not have to — the day it
+inspects your data model is the day it stops being usable outside this factory.
+What crosses the boundary is the **specification**, never the check.
+
+## Anti-patterns
+
+- **The instance that inherited its parent's lifecycle** — a fact about a
+  customer deleted because a setting changed. (M1, M2)
+- **Rebuild-by-delete as the implementation of "sync"** — shortest path, worst
+  blast radius. (M3)
+- **Business rules that exist only in the service layer** — true until a script,
+  a backfill, a second endpoint or a new join bypasses them. (M4)
+- **Identity enforced by a `Set` in memory** — dedupe in code where a unique
+  constraint belongs. (M5)
+- **One transaction spanning two aggregates** — the cascade's favourite vehicle.
+  (M6)
+- **`CASCADE` chosen because the store or ORM defaulted to it** — a default is
+  not a decision. (M1, §2)
+- **"It's only a backend change"** — the model *is* the backend; the diff
+  location is not the trigger. (§When this applies)
+- **A green suite that never populated the affected table** — a test that cannot
+  observe the destruction is not a test of it. (06g §3)
+- **Trusting a clean scan** — the tripwire is pattern-shaped and store-shaped;
+  it is not proof. (§5)
+- **Silent zero** — a missing filter reported as an empty day. (M8)
+- **Reading a scan exception as a clean deliverable** — an accepted finding is a
+  decision you must show, not a pass you may claim. (§4)
+- **Asking the loop guard to understand the model** — it verifies that specs are
+  done; teaching it cascade vocabulary puts a domain check in a general tool.
+  Capture the obligation as a spec instead. (§7)