@sigloch/contracts 2.0.0 → 3.1.0

package/dist/harness/index.d.ts

@@ -79,6 +79,15 @@ export declare const MutateCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     targetUid: z.ZodString;
 }, z.core.$strip>], "op">;
 export type MutateCommand = z.infer<typeof MutateCommandSchema>;
+export interface OpRisk {
+    destructive: boolean;
+    structural: boolean;
+}
+export declare const OP_RISK: Record<MutateCommand['op'], OpRisk>;
+/** True iff `op` removes data that is not recoverable by re-running the same op. */
+export declare function isDestructiveOp(op: MutateCommand['op']): boolean;
+/** True iff `op` changes graph topology (nodes/edges), not just attributes. */
+export declare function isStructuralOp(op: MutateCommand['op']): boolean;
 /** Monotone graph revision; incremented by +1 per successful mutate(). */
 export declare const GraphVersionSchema: z.ZodNumber;
 export type GraphVersion = z.infer<typeof GraphVersionSchema>;

package/dist/harness/index.js

@@ -93,6 +93,23 @@ export const MutateCommandSchema = z.discriminatedUnion('op', [
         targetUid: z.string(),
     }),
 ]);
+export const OP_RISK = {
+    'add-node': { destructive: false, structural: true },
+    'update-node': { destructive: false, structural: false },
+    'delete-node': { destructive: true, structural: true },
+    'add-edge': { destructive: false, structural: true },
+    'delete-edge': { destructive: true, structural: true },
+    'update-edge': { destructive: false, structural: true },
+    'merge-nodes': { destructive: true, structural: true },
+};
+/** True iff `op` removes data that is not recoverable by re-running the same op. */
+export function isDestructiveOp(op) {
+    return OP_RISK[op].destructive;
+}
+/** True iff `op` changes graph topology (nodes/edges), not just attributes. */
+export function isStructuralOp(op) {
+    return OP_RISK[op].structural;
+}
 // ---------------------------------------------------------------------------
 // CR-199: OCC — graph revision + optional baseVersion on mutate().
 // Schema-only here; revision counter/stale-check/delta live in the harness

package/dist/se/analysis-freshness-rules.d.ts

@@ -0,0 +1,39 @@
+/**
+ * CR-SM-227: Analysis-Freshness-Legs — the third leg-kind a review gate checks
+ * (rule legs, layer-presence legs [R-28], now analysis-freshness legs).
+ * Presence/Resolution-Split (wie R-19/R-20/R-26/R-27 vs. RC-01..05): these five
+ * rules are the PRÜFBARE FORM only — does a `graphVersion` stamp exist for the
+ * artifact, as a graph attribute. They never compare the stamp against the
+ * live graphVersion (that staleness/currency check is I/O — a consumer
+ * concern, `CreationCurrencyProvider` in `@sigloch/graphcode-client`).
+ */
+import type { OntologyGraph } from './ontology.js';
+import type { RuleViolation } from './rules.js';
+export declare const AF_RULES: readonly [{
+    readonly id: "AF-01";
+    readonly name: "ConOps freshness stamp present";
+    readonly severity: "warning";
+    readonly evaluate: (graph: OntologyGraph) => RuleViolation[];
+}, {
+    readonly id: "AF-02";
+    readonly name: "Trade Study freshness stamp present";
+    readonly severity: "warning";
+    readonly evaluate: (graph: OntologyGraph) => RuleViolation[];
+}, {
+    readonly id: "AF-03";
+    readonly name: "Assumption Review freshness stamp present";
+    readonly severity: "warning";
+    readonly evaluate: (graph: OntologyGraph) => RuleViolation[];
+}, {
+    readonly id: "AF-04";
+    readonly name: "FMEA freshness stamp present";
+    readonly severity: "warning";
+    readonly evaluate: (graph: OntologyGraph) => RuleViolation[];
+}, {
+    readonly id: "AF-05";
+    readonly name: "Implementation Plan freshness stamp present";
+    readonly severity: "warning";
+    readonly evaluate: (graph: OntologyGraph) => RuleViolation[];
+}];
+/** Evaluate all analysis-freshness-presence rules. */
+export declare function evaluateAFRules(graph: OntologyGraph): RuleViolation[];

package/dist/se/analysis-freshness-rules.js

@@ -0,0 +1,44 @@
+import { AnalysisFreshnessStampSchema } from './ontology.js';
+const ARTIFACT_LABEL = {
+    conops: 'Concept of Operations',
+    trade: 'Trade Study',
+    'assumption-review': 'Assumption Review',
+    fmea: 'FMEA',
+    implplan: 'Implementation Plan',
+};
+/** Presence-check for one analysis artifact's freshness stamp, anchored on SYS (like R-28). */
+function analysisFreshnessPresence(ruleId, artifactId) {
+    return (graph) => {
+        const sys = graph.elements.find(e => e.type === 'SYS');
+        if (!sys)
+            return []; // nothing to anchor on yet (same vacuous-complete exemption as R-28)
+        const stamp = sys.attributes?.analysisFreshness?.[artifactId];
+        if (AnalysisFreshnessStampSchema.safeParse(stamp).success)
+            return [];
+        const label = ARTIFACT_LABEL[artifactId];
+        return [{
+                rule_id: ruleId,
+                severity: 'warning',
+                element_id: sys.id,
+                message: `${label} (${artifactId}) has no freshness stamp — was it ever written with a graphVersion stamp?`,
+                fix_hint: `Set attributes.analysisFreshness.${artifactId}.graphVersion to the current graphVersion() when writing/refreshing the ${label} artifact`,
+                context: { element_type: sys.type, element_name: sys.name },
+            }];
+    };
+}
+const conopsFreshnessPresent = analysisFreshnessPresence('AF-01', 'conops');
+const tradeFreshnessPresent = analysisFreshnessPresence('AF-02', 'trade');
+const assumptionReviewFreshnessPresent = analysisFreshnessPresence('AF-03', 'assumption-review');
+const fmeaFreshnessPresent = analysisFreshnessPresence('AF-04', 'fmea');
+const implplanFreshnessPresent = analysisFreshnessPresence('AF-05', 'implplan');
+export const AF_RULES = [
+    { id: 'AF-01', name: 'ConOps freshness stamp present', severity: 'warning', evaluate: conopsFreshnessPresent },
+    { id: 'AF-02', name: 'Trade Study freshness stamp present', severity: 'warning', evaluate: tradeFreshnessPresent },
+    { id: 'AF-03', name: 'Assumption Review freshness stamp present', severity: 'warning', evaluate: assumptionReviewFreshnessPresent },
+    { id: 'AF-04', name: 'FMEA freshness stamp present', severity: 'warning', evaluate: fmeaFreshnessPresent },
+    { id: 'AF-05', name: 'Implementation Plan freshness stamp present', severity: 'warning', evaluate: implplanFreshnessPresent },
+];
+/** Evaluate all analysis-freshness-presence rules. */
+export function evaluateAFRules(graph) {
+    return AF_RULES.flatMap(r => r.evaluate(graph));
+}

package/dist/se/ao-rules.d.ts

@@ -52,7 +52,7 @@ export declare const AO_RULES: readonly [{
     readonly evaluate: typeof ca01CapabilityAllocation;
 }, {
     readonly id: "IO-01";
-    readonly name: "CrossModuleIOCompleteness";
+    readonly name: "FuncPairIOCompleteness";
     readonly severity: "warning";
     readonly evaluate: typeof io01CrossModuleCompleteness;
 }];

package/dist/se/ao-rules.js

@@ -256,8 +256,12 @@ export function ca01CapabilityAllocation(graph) {
     return violations;
 }
 // ---------------------------------------------------------------------------
-// IO-01: Cross-module IO completeness (CR-192)
-// For each FCHAIN, FUNCs in different MODs must have a FLOW path between them.
+// IO-01: FUNC-pair IO completeness (CR-192, extended CR-SM-226)
+// For each FCHAIN with ≥2 FUNCs, every pair of FUNCs in the chain must have a
+// FLOW path between them — not just pairs allocated to different MODs.
+// CR-SM-226 removed the cross-module-only restriction: same-module FUNC
+// pairs need an explicit FLOW just as much (module allocation is an
+// orthogonal concern to whether the interaction itself is wired up).
 // ---------------------------------------------------------------------------
 export function io01CrossModuleCompleteness(graph) {
     const violations = [];
@@ -270,23 +274,21 @@ export function io01CrossModuleCompleteness(graph) {
             .filter(id => graph.elements.some(e => e.id === id && e.type === 'FUNC'));
         if (funcIds.length < 2)
             continue;
-        // Map FUNC→MOD via allocate
+        // Map FUNC→MOD via allocate (kept for the message context; no longer a filter).
         const funcToMod = new Map();
         for (const fid of funcIds) {
             const allocTrace = graph.traces.find(t => t.source === fid && t.type === 'allocate');
             if (allocTrace)
                 funcToMod.set(fid, allocTrace.target);
         }
-        // For each pair of FUNCs in different MODs, check for FLOW path
+        // For each pair of FUNCs in the chain, check for a FLOW path.
         const checked = new Set();
         for (const fA of funcIds) {
             for (const fB of funcIds) {
                 if (fA >= fB)
                     continue;
-                const modA = funcToMod.get(fA);
-                const modB = funcToMod.get(fB);
-                if (!modA || !modB || modA === modB)
-                    continue;
+                const modA = funcToMod.get(fA) ?? 'unallocated';
+                const modB = funcToMod.get(fB) ?? 'unallocated';
                 const pairKey = `${fA}:${fB}`;
                 if (checked.has(pairKey))
                     continue;
@@ -314,7 +316,7 @@ export function io01CrossModuleCompleteness(graph) {
                         severity: 'warning',
                         element_id: fA,
                         message: `${fA} (${modA}) and ${fB} (${modB}) in FCHAIN ${fc.id} have no IO path — missing FLOW?`,
-                        fix_hint: 'Add a FLOW element with io traces between these cross-module functions',
+                        fix_hint: 'Add a FLOW element with io traces between these functions',
                         context: {
                             element_type: 'FUNC',
                             element_name: elA?.name ?? fA,
@@ -334,7 +336,7 @@ export const AO_RULES = [
     { id: 'RT-01', name: 'PhysicalBoundaryIntegrity', severity: 'error', evaluate: rt01PhysicalBoundaryIntegrity },
     { id: 'PH-01', name: 'PhysicalModCompleteness', severity: 'info', evaluate: ph01PhysicalModCompleteness },
     { id: 'CA-01', name: 'CapabilityAllocation', severity: 'error', evaluate: ca01CapabilityAllocation },
-    { id: 'IO-01', name: 'CrossModuleIOCompleteness', severity: 'warning', evaluate: io01CrossModuleCompleteness },
+    { id: 'IO-01', name: 'FuncPairIOCompleteness', severity: 'warning', evaluate: io01CrossModuleCompleteness },
 ];
 export function evaluateAORules(graph) {
     return AO_RULES.flatMap(r => r.evaluate(graph));

package/dist/se/evaluate-all.js

@@ -9,6 +9,7 @@ import { CR_RULES, evaluateCRRules } from './cr-quality-rules.js';
 import { ND_RULES, evaluateNDRules } from './near-duplicate-rules.js';
 import { AO_RULES, evaluateAORules } from './ao-rules.js';
 import { BQ_RULES, evaluateBQRules } from './quality-rules.js';
+import { AF_RULES, evaluateAFRules } from './analysis-freshness-rules.js';
 /** All prescribed rule definitions (single source of truth for the catalog). */
 export const ALL_RULE_DEFS = [
     ...V3_RULES.map(r => ({ id: r.id, name: r.name, severity: r.severity })),
@@ -22,10 +23,11 @@ export const ALL_RULE_DEFS = [
     ...AO_RULES.map(r => ({ id: r.id, name: r.name, severity: r.severity })),
     ...FM_RULES.map(r => ({ id: r.id, name: r.name, severity: r.severity })),
     ...VIEW_RULES.map(r => ({ id: r.id, name: r.name, severity: r.severity })),
+    ...AF_RULES.map(r => ({ id: r.id, name: r.name, severity: r.severity })),
 ];
 // CR-SM-221: 'RD-' was missing — 'RD-01'.startsWith('R-') is false, so the
 // decomposition rules ran in `default` only and never in the `se` profile.
-const SE_PREFIXES = ['R-', 'RD-', 'UC-', 'FC-', 'SC-', 'MT-', 'CR-', 'AO-', 'FM-', 'NFR-', 'RT-', 'PH-', 'CA-', 'IO-', 'VR-', 'CL-'];
+const SE_PREFIXES = ['R-', 'RD-', 'UC-', 'FC-', 'SC-', 'MT-', 'CR-', 'AO-', 'FM-', 'NFR-', 'RT-', 'PH-', 'CA-', 'IO-', 'VR-', 'CL-', 'AF-'];
 const CODING_PREFIXES = ['BQ-', 'ND-'];
 export function getRuleDefsForProfile(profile) {
     if (profile === 'se')
@@ -48,5 +50,6 @@ export function evaluateAllRules(graph) {
         ...evaluateAORules(graph),
         ...evaluateFMRules(graph),
         ...evaluateViewRules(graph),
+        ...evaluateAFRules(graph),
     ];
 }

package/dist/se/fchain-quality-rules.d.ts

@@ -6,5 +6,6 @@ import type { RuleDefinition, RuleViolation } from './rules.js';
 export declare function fc01ActorBoundary(graph: OntologyGraph): RuleViolation[];
 export declare function fc02LeafUcHasFchain(graph: OntologyGraph): RuleViolation[];
 export declare function fc03FchainFlat(graph: OntologyGraph): RuleViolation[];
+export declare function fc04ActorBounded(graph: OntologyGraph): RuleViolation[];
 export declare const FC_RULES: RuleDefinition[];
 export declare function evaluateFCRules(graph: OntologyGraph): RuleViolation[];

package/dist/se/fchain-quality-rules.js

@@ -93,12 +93,55 @@ export function fc03FchainFlat(graph) {
     return violations;
 }
 // ---------------------------------------------------------------------------
+// FC-04: FCHAIN is actor-bounded — trigger AND consumer (CR-SM-226).
+// Distinct from FC-01: FC-01 is satisfied by ANY single actor connection (one
+// direction only), and even allows a UC-level bypass (the parent UC's own
+// ACTOR io counts, with no FUNC-level connection at all). FC-04 is stricter —
+// it requires BOTH an entry (ACTOR→FLOW→FUNC∈chain, something triggers the
+// chain) AND an exit (FUNC∈chain→FLOW→ACTOR, the chain produces something
+// back to an actor), evaluated purely at the FUNC/FLOW level. This catches
+// the "hollow chain" FC-01 cannot see: a chain with an entry but no exit (or
+// vice versa), or one that only looks bounded because its parent UC happens
+// to have unrelated ACTOR io.
+// ---------------------------------------------------------------------------
+export function fc04ActorBounded(graph) {
+    return graph.elements
+        .filter(e => e.type === 'FCHAIN')
+        .filter(fc => {
+        const funcIds = new Set(graph.traces
+            .filter(t => t.source === fc.id && t.type === 'compose')
+            .map(t => t.target)
+            .filter(id => graph.elements.some(e => e.id === id && e.type === 'FUNC')));
+        if (funcIds.size === 0)
+            return false; // R-15 already flags the empty-chain case
+        const io = graph.traces.filter(t => t.type === 'io');
+        const isActor = (id) => graph.elements.some(e => e.id === id && e.type === 'ACTOR');
+        const isFlow = (id) => graph.elements.some(e => e.id === id && e.type === 'FLOW');
+        // Entry: ACTOR→FLOW→FUNC∈chain (something triggers the chain).
+        const entry = io.some(e => funcIds.has(e.target) && isFlow(e.source) &&
+            io.some(a => a.target === e.source && isActor(a.source)));
+        // Exit: FUNC∈chain→FLOW→ACTOR (the chain produces something back to an actor).
+        const exit = io.some(e => funcIds.has(e.source) && isFlow(e.target) &&
+            io.some(a => a.source === e.target && isActor(a.target)));
+        return !(entry && exit);
+    })
+        .map(fc => ({
+        rule_id: 'FC-04',
+        severity: 'warning',
+        element_id: fc.id,
+        message: `${fc.id} is not actor-bounded (needs an ACTOR trigger into AND an ACTOR consumer out of the chain)`,
+        fix_hint: 'Link an ACTOR→FLOW→FUNC entry and a FUNC→FLOW→ACTOR exit for at least one FUNC in the chain',
+        context: { element_type: fc.type, element_name: fc.name },
+    }));
+}
+// ---------------------------------------------------------------------------
 // Aggregated
 // ---------------------------------------------------------------------------
 export const FC_RULES = [
     { id: 'FC-01', name: 'FCHAIN has actor boundary', severity: 'warning', evaluate: fc01ActorBoundary },
     { id: 'FC-02', name: 'Leaf UC has FCHAIN', severity: 'warning', evaluate: fc02LeafUcHasFchain },
     { id: 'FC-03', name: 'FCHAIN is flat', severity: 'warning', evaluate: fc03FchainFlat },
+    { id: 'FC-04', name: 'FCHAIN actor-bounded (trigger+consumer)', severity: 'warning', evaluate: fc04ActorBounded },
 ];
 export function evaluateFCRules(graph) {
     return FC_RULES.flatMap(rule => rule.evaluate(graph));

package/dist/se/index.d.ts

@@ -5,7 +5,7 @@
 /** Ontology schema version (element types + trace types). */
 export declare const ONTOLOGY_VERSION = "4.0.0";
 /** Rules engine version (validation rules incl. RC conformance). */
-export declare const RULES_VERSION = "2.21.0";
+export declare const RULES_VERSION = "2.23.0";
 /** Meta-model version (trace pattern constraints + format-e parser). */
 export declare const META_MODEL_VERSION = "1.4.0";
 export * from './ontology.js';
@@ -21,6 +21,7 @@ export * from './cr-quality-rules.js';
 export * from './near-duplicate-rules.js';
 export * from './ao-rules.js';
 export * from './quality-rules.js';
+export * from './analysis-freshness-rules.js';
 export * from './evaluate-all.js';
 export * from './readiness.js';
 export * from './meta-model.js';

package/dist/se/index.js

@@ -5,7 +5,7 @@
 /** Ontology schema version (element types + trace types). */
 export const ONTOLOGY_VERSION = '4.0.0'; // BREAKING: `SemanticId` (`Name.TypeAbbr.Counter`) deleted, `ElementUid` (`<TYPE>-<slug>`) is the family canon — the old canon was used by no production graph of the family while 626 of 1145 elements already carried TYPE-slug (CR-SM-217); realRef unifies codeRef+schemaRef (+physical-MOD CAD ref), symbol optional; testRef stays separate (CR-228 C); +RepoRelativePathSchema on testRef/realRef .file — no absolute/`..` paths (CR-GC-255)
 /** Rules engine version (validation rules incl. RC conformance). */
-export const RULES_VERSION = '2.21.0'; // -MT-03 retired as a rule and reborn as the `allocationCohesion` measurement (CR-SM-223): the 80 % threshold fired on 6/7 graphcode, 4/4 gve and 10/11 family modules — in a flow-routed architecture cross-boundary interaction is the design, not a defect; the metric now reports internal/external per MOD, worst-first, and stays out of the violation stream so it cannot depress the readiness score; +RD-04 decomposition breadth (>11 children per level → warning) and MT-03 recalibrated to FLOW-transitive connection pairs — counting raw io traces reported internal=0 on every real SE graph (15/15 false positives), because the meta-model routes FUNC↔FUNC through FLOW; 'RD-' added to the se profile prefixes, where RD-01..04 were silently missing (CR-SM-221); -SC-01/-SC-03 deleted (BOK-CR-026): `realRef` is the single SCHEMA binding truth (R-26 presence, RC-03/RC-04 resolution); the legacy `zodDefinition`/`sourceFile`/`sourceExport` attributes are gone from every producer, SC_RULES = [SC-02]; R-20/R-26/RC-01/RC-03/RC-04 read realRef (unified codeRef+schemaRef); +R-27 physical-MOD realRef presence (CR-228 C); -R-24/R-25 REQ→MOD allocation rules deleted (CR-228 A: REQ→MOD allocate no longer a valid pattern, R-18 flags residual edges); NFR-01 budget target split physical→MOD / behavioral→FCHAIN; RULE_TO_DIMENSION completeness (R-18..R-23/R-26/MS-03/CR-R04 mapped, no advisory fall-through) (CR-228 B/D); +BQ-01/02/04/06/07 base-quality rules promoted from aimpro (K2-b, completes rule consolidation); +ND-01/02 near-duplicate + AO-D01/D03/CR-01/RT-01/PH-01/CA-01/IO-01 architecture rules promoted from aimpro (K2-b); +CR-R01..04/MS-03 change-request rules promoted from aimpro (K2-b); +FM-01..03/NFR-01 FMEA + VR-01/CL-01 view rules promoted from aimpro (K2-b); +MT-01..03 architecture metrics promoted from aimpro (K2-b); +SC-01..03/UC-01..06/FC-01..03 quality rules promoted from aimpro (K2-a); +RC-05 cross-module import drift (CR-212); +R-26/RC-03/RC-04 schemaRef (CR-211); +R-22..R-25/R-10/R-20 (CR-201/202/208/209/210)
+export const RULES_VERSION = '2.23.0'; // CR-SM-227: +AF-01..05 Analysis-Freshness-Legs (analysis-freshness-rules.ts) — the third leg-kind a review gate checks (rule legs, layer-presence legs [R-28], now analysis-freshness legs, docs/articles/07-the-scoring-landscape.md); presence-only rules (Presence/Resolution-Split like R-19/R-20/R-26/R-27 vs. RC-01..05) checking a `graphVersion` freshness stamp exists under SYS.attributes.analysisFreshness.<AnalysisArtifactId> for each of the 5 CR-GC-221 judgment artifacts (conops/trade/assumption-review/fmea/implplan) — staleness (stamp vs live graphVersion) stays a consumer/I-O concern (`CreationCurrencyProvider`, @sigloch/graphcode-client), NOT evaluated here; Familie-Review 2026-08-05 gate assignment → RULE_TO_PHASE: ConOps/Trade/Assumption-Review → PDR, FMEA → CDR, Implementation Plan → TRR (SRR gets none); +AnalysisArtifactId enum + AnalysisFreshnessStampSchema (ontology.ts) as the SSOT graphcode-client's ARTIFACT_CATALOG analysis ids must match; grober Graph-Versions-Stempel only, no scope-hash in this first cut (conscious CR-SM-227 limitation).
 /** Meta-model version (trace pattern constraints + format-e parser). */
 export const META_MODEL_VERSION = '1.4.0'; // -REQ→MOD allocate pattern removed (CR-228 A); +FUNC→FUNC compose (blackbox function decomposition)
 export * from './ontology.js';
@@ -21,6 +21,7 @@ export * from './cr-quality-rules.js';
 export * from './near-duplicate-rules.js';
 export * from './ao-rules.js';
 export * from './quality-rules.js';
+export * from './analysis-freshness-rules.js';
 export * from './evaluate-all.js';
 export * from './readiness.js';
 export * from './meta-model.js';

package/dist/se/ontology.d.ts

@@ -131,6 +131,34 @@ export declare const RealRefSchema: z.ZodObject<{
     lang: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type RealRef = z.infer<typeof RealRefSchema>;
+/**
+ * The five judgment-work artifact ids (CR-GC-221's creation keys) that graphcode's
+ * skills produce and that a phase gate checks for presence+freshness (CR-SM-227).
+ * SSOT — `@sigloch/graphcode-client`'s `ARTIFACT_CATALOG` (`kind:'analysis'` rows)
+ * must use exactly these ids.
+ */
+export declare const AnalysisArtifactId: z.ZodEnum<{
+    conops: "conops";
+    fmea: "fmea";
+    trade: "trade";
+    implplan: "implplan";
+    "assumption-review": "assumption-review";
+}>;
+export type AnalysisArtifactId = z.infer<typeof AnalysisArtifactId>;
+/**
+ * A "this analysis covers graph-stand V" stamp (CR-SM-227) — the grober
+ * Graph-Versions-Stempel Familie-Review decided (no scope-hash in the first
+ * cut, see CR-SM-227 "Achtung"). `graphVersion` is the harness's monotone
+ * counter (`ToolContext.graphVersion()`, graphcode) at the moment the
+ * artifact was written — I/O, so writing it stays a consumer (graphcode)
+ * concern; contracts only defines the shape.
+ * Stored under `OntologyElement.attributes.analysisFreshness.<AnalysisArtifactId>`
+ * on the SYS root element (same anchor convention as R-28).
+ */
+export declare const AnalysisFreshnessStampSchema: z.ZodObject<{
+    graphVersion: z.ZodNumber;
+}, z.core.$strip>;
+export type AnalysisFreshnessStamp = z.infer<typeof AnalysisFreshnessStampSchema>;
 /**
  * An element (node) in the SE ontology graph.
  * `attributes` holds type-specific properties (e.g. FUNC.safety_relevant).

package/dist/se/ontology.js

@@ -92,6 +92,26 @@ export const RealRefSchema = z.object({
     symbol: z.string().optional(),
     lang: z.string().optional(),
 });
+/**
+ * The five judgment-work artifact ids (CR-GC-221's creation keys) that graphcode's
+ * skills produce and that a phase gate checks for presence+freshness (CR-SM-227).
+ * SSOT — `@sigloch/graphcode-client`'s `ARTIFACT_CATALOG` (`kind:'analysis'` rows)
+ * must use exactly these ids.
+ */
+export const AnalysisArtifactId = z.enum(['conops', 'fmea', 'trade', 'implplan', 'assumption-review']);
+/**
+ * A "this analysis covers graph-stand V" stamp (CR-SM-227) — the grober
+ * Graph-Versions-Stempel Familie-Review decided (no scope-hash in the first
+ * cut, see CR-SM-227 "Achtung"). `graphVersion` is the harness's monotone
+ * counter (`ToolContext.graphVersion()`, graphcode) at the moment the
+ * artifact was written — I/O, so writing it stays a consumer (graphcode)
+ * concern; contracts only defines the shape.
+ * Stored under `OntologyElement.attributes.analysisFreshness.<AnalysisArtifactId>`
+ * on the SYS root element (same anchor convention as R-28).
+ */
+export const AnalysisFreshnessStampSchema = z.object({
+    graphVersion: z.number().int().nonnegative(),
+});
 /**
  * An element (node) in the SE ontology graph.
  * `attributes` holds type-specific properties (e.g. FUNC.safety_relevant).

package/dist/se/readiness.d.ts

@@ -1,6 +1,11 @@
 /**
  * CR-120: Readiness dimension schemas for dynamic phase readiness.
  * Dimensions emerge from graph state — no state machine.
+ * CR-SM-226: `emergentPhase`/`phaseScore` (CR-120/146) removed — a third,
+ * undocumented phase construct next to RULE_TO_DIMENSION and the (then still
+ * ad-hoc) phase-gate grouping. `RULE_TO_PHASE` below is the one replacement:
+ * a rule → SRR/PDR/CDR/TRR mapping, same shape and same completeness
+ * guarantee as `RULE_TO_DIMENSION`, exported so no consumer reinvents it.
  */
 import { z } from 'zod/v4';
 export declare const ReadinessDimension: z.ZodEnum<{
@@ -48,8 +53,6 @@ export declare const ReadinessReport: z.ZodObject<{
         applicable: z.ZodNumber;
         ready: z.ZodBoolean;
     }, z.core.$strip>>;
-    emergentPhase: z.ZodString;
-    phaseScore: z.ZodNumber;
     overallScore: z.ZodNumber;
     timestamp: z.ZodISODateTime;
 }, z.core.$strip>;
@@ -60,3 +63,24 @@ export type ReadinessReportType = z.infer<typeof ReadinessReport>;
  * since its core concern is test verification coverage.
  */
 export declare const RULE_TO_DIMENSION: Record<string, ReadinessDimensionType>;
+/** INCOSE technical-review gates, in lifecycle order. */
+export declare const PhaseGate: z.ZodEnum<{
+    SRR: "SRR";
+    PDR: "PDR";
+    CDR: "CDR";
+    TRR: "TRR";
+}>;
+export type PhaseGateType = z.infer<typeof PhaseGate>;
+/**
+ * Rule → phase-gate mapping (CR-SM-226). SRR = requirements/scope clarity,
+ * PDR = architecture/functional completeness, CDR = critical design/schema
+ * completeness, TRR = test readiness. Primary-gate assignment, same
+ * single-owner convention as RULE_TO_DIMENSION.
+ */
+export declare const RULE_TO_PHASE: Record<string, PhaseGateType>;
+/** The 8 RULE_TO_DIMENSION topic scores (req/uc/arch/alloc/ver/schema/cr/ms). */
+export declare const DIMENSION_READINESS_NAME = "dimension_readiness";
+/** The 4 RULE_TO_PHASE gate scores (SRR/PDR/CDR/TRR). */
+export declare const PHASE_READINESS_NAME = "phase_readiness";
+/** Best-of-N ranking KPI: candidate dimension_readiness minus baseline. */
+export declare const DIMENSION_READINESS_DELTA_NAME = "dimension_readiness_delta";

package/dist/se/readiness.js

@@ -1,15 +1,20 @@
 /**
  * CR-120: Readiness dimension schemas for dynamic phase readiness.
  * Dimensions emerge from graph state — no state machine.
+ * CR-SM-226: `emergentPhase`/`phaseScore` (CR-120/146) removed — a third,
+ * undocumented phase construct next to RULE_TO_DIMENSION and the (then still
+ * ad-hoc) phase-gate grouping. `RULE_TO_PHASE` below is the one replacement:
+ * a rule → SRR/PDR/CDR/TRR mapping, same shape and same completeness
+ * guarantee as `RULE_TO_DIMENSION`, exported so no consumer reinvents it.
  */
 import { z } from 'zod/v4';
 export const ReadinessDimension = z.enum([
     'req', // Requirements quality (BQ-01..07, RD-01..03)
-    'uc', // UC completeness (UC-01..06, R-14, FC-01..03)
+    'uc', // UC completeness (UC-01..06, R-14, FC-01..04)
     'arch', // Functional architecture (R-02, R-03, R-10, R-12)
     'alloc', // Module allocation (R-04)
     'ver', // Test coverage (R-01, R-05)
-    'schema', // Interface completeness (R-26 binding, SC-02 usage)
+    'schema', // Interface completeness (R-26 binding, SC-02/SC-04 usage)
     'cr', // CR traceability (CR-R01..R03)
     'ms', // Milestone planning (MS-01..02)
 ]);
@@ -22,8 +27,6 @@ export const ReadinessScore = z.object({
 });
 export const ReadinessReport = z.object({
     scores: z.array(ReadinessScore),
-    emergentPhase: z.string(),
-    phaseScore: z.number().min(0).max(1), // CR-146: % progress of current phase
     overallScore: z.number().min(0).max(1),
     timestamp: z.iso.datetime(),
 });
@@ -42,11 +45,14 @@ export const RULE_TO_DIMENSION = {
     // trace/realization/allocation completeness rules (CR-228 D: previously unmapped → advisory fall-through)
     'R-18': 'arch', 'R-19': 'ver', 'R-20': 'arch', 'R-21': 'ver',
     'R-22': 'alloc', 'R-23': 'alloc', 'R-26': 'schema', 'R-27': 'arch',
+    // CR-SM-226: R-28 Ebenen-Präsenz (>1 FUNC needs FLOW+SCHEMA) is an architecture rule.
+    'R-28': 'arch',
     // uc
     'UC-01': 'uc', 'UC-02': 'uc', 'UC-03': 'uc', 'UC-04': 'uc',
     'UC-05': 'uc', 'UC-06': 'uc',
     'R-14': 'uc', 'R-15': 'uc', 'R-16': 'uc', 'R-17': 'uc',
-    'FC-01': 'uc', 'FC-02': 'uc', 'FC-03': 'uc',
+    // FC-04 (CR-SM-226): FCHAIN actor-bounded (trigger+consumer) — same dimension as FC-01..03.
+    'FC-01': 'uc', 'FC-02': 'uc', 'FC-03': 'uc', 'FC-04': 'uc',
     // arch
     'R-02': 'arch', 'R-03': 'arch', 'R-10': 'arch', 'R-12': 'arch',
     // alloc
@@ -55,6 +61,8 @@ export const RULE_TO_DIMENSION = {
     'R-01': 'ver', 'R-05': 'ver',
     // schema
     'SC-02': 'schema', // SC-01/SC-03 deleted (BOK-CR-026) — R-26 is the binding rule
+    // CR-SM-226: SC-04 sharp per-FLOW SCHEMA-binding check — same dimension as SC-02.
+    'SC-04': 'schema',
     // structural rules without primary dimension → assigned by closest concern
     'R-08': 'arch',
     // near-duplicate detection
@@ -73,6 +81,11 @@ export const RULE_TO_DIMENSION = {
     'MS-01': 'ms', 'MS-02': 'ms', 'MS-03': 'ms',
     // FMEA / risk
     'FM-01': 'req', 'FM-02': 'req', 'FM-03': 'ver',
+    // CR-SM-227: analysis-artifact freshness presence — closest topical fit per artifact.
+    'AF-01': 'req', 'AF-03': 'req', // ConOps/Assumption-Review: requirements-adjacent judgment work
+    'AF-02': 'arch', // Trade Study: architecture decision record
+    'AF-04': 'ver', // FMEA: risk/verification, same bucket as FM-03
+    'AF-05': 'ms', // Implementation Plan: milestone/planning
     // NFR budget
     'NFR-01': 'arch',
     // cross-module IO (CR-192)
@@ -81,3 +94,71 @@ export const RULE_TO_DIMENSION = {
     'VR-01': 'ver',
     'CL-01': 'uc',
 };
+// ---------------------------------------------------------------------------
+// Phase-gate readiness (CR-SM-226) — the INCOSE technical-review axis.
+// Orthogonal to RULE_TO_DIMENSION (8 topic scores): RULE_TO_PHASE groups the
+// SAME rule violations into the 4 lifecycle gates SRR/PDR/CDR/TRR. Both are
+// projections of one rule stream — "three views over the same rule
+// violations" (docs/articles/07-the-scoring-landscape.md), not three
+// independent scoring systems. No advisory fall-through: every rule in
+// ALL_RULE_DEFS must appear here (enforced by a completeness test analogous
+// to the RULE_TO_DIMENSION one).
+// ---------------------------------------------------------------------------
+/** INCOSE technical-review gates, in lifecycle order. */
+export const PhaseGate = z.enum(['SRR', 'PDR', 'CDR', 'TRR']);
+/**
+ * Rule → phase-gate mapping (CR-SM-226). SRR = requirements/scope clarity,
+ * PDR = architecture/functional completeness, CDR = critical design/schema
+ * completeness, TRR = test readiness. Primary-gate assignment, same
+ * single-owner convention as RULE_TO_DIMENSION.
+ */
+export const RULE_TO_PHASE = {
+    // CR-SM-227: Analysis-Freshness-Legs (AF-01..05) — Familie-Review 2026-08-05
+    // gate assignment, final: ConOps/Trade/Assumption-Review → PDR, FMEA → CDR,
+    // Implementation Plan → TRR. SRR gets no analysis-freshness leg.
+    'AF-01': 'PDR', 'AF-02': 'PDR', 'AF-03': 'PDR', // ConOps, Trade Study, Assumption Review
+    'AF-04': 'CDR', // FMEA
+    'AF-05': 'TRR', // Implementation Plan
+    // SRR — requirements/scope clarity, system+UC boundary definition.
+    'BQ-01': 'SRR', 'BQ-02': 'SRR', 'BQ-04': 'SRR', 'BQ-06': 'SRR', 'BQ-07': 'SRR',
+    'RD-01': 'SRR', 'RD-02': 'SRR', 'RD-03': 'SRR',
+    'UC-01': 'SRR', 'UC-02': 'SRR', 'UC-03': 'SRR', 'UC-04': 'SRR', 'UC-05': 'SRR', 'UC-06': 'SRR',
+    'R-14': 'SRR', 'R-16': 'SRR', 'R-17': 'SRR',
+    'FC-02': 'SRR',
+    'CL-01': 'SRR',
+    'FM-01': 'SRR', 'FM-02': 'SRR',
+    'CR-R01': 'SRR', 'CR-R03': 'SRR',
+    'MS-01': 'SRR', 'MS-02': 'SRR', 'MS-03': 'SRR',
+    // PDR — architecture/functional completeness.
+    'RD-04': 'PDR',
+    'R-02': 'PDR', 'R-03': 'PDR', 'R-08': 'PDR', 'R-10': 'PDR', 'R-12': 'PDR', 'R-18': 'PDR',
+    'R-04': 'PDR', 'R-22': 'PDR', 'R-23': 'PDR',
+    'R-15': 'PDR',
+    'FC-01': 'PDR', 'FC-03': 'PDR', 'FC-04': 'PDR',
+    'R-28': 'PDR', // Ebenen-Präsenz (CR-SM-226)
+    'MT-01': 'PDR', 'MT-02': 'PDR',
+    'ND-01': 'PDR',
+    'AO-D01': 'PDR', 'AO-D03': 'PDR', 'CR-01': 'PDR', 'RT-01': 'PDR', 'PH-01': 'PDR', 'CA-01': 'PDR',
+    'IO-01': 'PDR', // CR-SM-226: extended to all FCHAIN FUNC-pairs, added to the phase axis.
+    'CR-R04': 'PDR',
+    // CDR — critical design/schema completeness.
+    'R-26': 'CDR', 'R-27': 'CDR',
+    'SC-02': 'CDR', 'SC-04': 'CDR', // SC-04: FLOW→SCHEMA sharp rule (CR-SM-226)
+    'ND-02': 'CDR',
+    'NFR-01': 'CDR',
+    // TRR — test readiness.
+    'R-01': 'TRR', 'R-05': 'TRR', 'R-19': 'TRR', 'R-20': 'TRR', 'R-21': 'TRR',
+    'VR-01': 'TRR',
+    'FM-03': 'TRR',
+    'CR-R02': 'TRR',
+};
+// ---------------------------------------------------------------------------
+// Sprachregelung (CR-SM-226) — naming SSOT so graphcode/graph-view-edit/
+// article render the same terms instead of re-inventing string literals.
+// ---------------------------------------------------------------------------
+/** The 8 RULE_TO_DIMENSION topic scores (req/uc/arch/alloc/ver/schema/cr/ms). */
+export const DIMENSION_READINESS_NAME = 'dimension_readiness';
+/** The 4 RULE_TO_PHASE gate scores (SRR/PDR/CDR/TRR). */
+export const PHASE_READINESS_NAME = 'phase_readiness';
+/** Best-of-N ranking KPI: candidate dimension_readiness minus baseline. */
+export const DIMENSION_READINESS_DELTA_NAME = 'dimension_readiness_delta';

package/dist/se/rules.js

@@ -898,6 +898,41 @@ function physicalModMustHaveRealRef(graph) {
         context: { element_type: mod.type, element_name: mod.name },
     }));
 }
+// ---------------------------------------------------------------------------
+// R-28: Ebenen-Präsenz — architecture-level presence (CR-SM-226).
+// Closes the vacuous-complete hole: with 0 or 1 FUNC, per-element rules like
+// R-15/FC-04/SC-04 fire 0 times and every completeness leg reads "complete" —
+// not because the architecture is done, but because there is nothing to check
+// yet. Once >1 FUNC exists, the graph must ALSO carry at least one FLOW (data
+// moves between functions) AND at least one SCHEMA (that data has a
+// contract) — ONE combined rule, not staged PDR/CDR checks (the CR draft's
+// two-stage proposal was simplified in Familie-Review 2026-08-04).
+// ---------------------------------------------------------------------------
+function ebenenPraesenz(graph) {
+    const funcs = graph.elements.filter(e => e.type === 'FUNC');
+    if (funcs.length <= 1)
+        return [];
+    const flows = graph.elements.filter(e => e.type === 'FLOW');
+    const schemas = graph.elements.filter(e => e.type === 'SCHEMA');
+    const missingLevels = [];
+    if (flows.length === 0)
+        missingLevels.push('FLOW');
+    if (schemas.length === 0)
+        missingLevels.push('SCHEMA');
+    if (missingLevels.length === 0)
+        return [];
+    // Anchor the graph-wide violation on SYS (the root) if present, else the
+    // first FUNC — there is no single "population" element this rule checks.
+    const anchor = graph.elements.find(e => e.type === 'SYS') ?? funcs[0];
+    return [{
+            rule_id: 'R-28',
+            severity: 'warning',
+            element_id: anchor.id,
+            message: `Graph has ${funcs.length} FUNCs but no ${missingLevels.join(' and no ')} element — architecture level(s) absent`,
+            fix_hint: `Add at least one ${missingLevels.join(' and one ')} element to bind the functional and data-level architecture`,
+            context: { element_type: anchor.type, element_name: anchor.name },
+        }];
+}
 export const V3_RULES = [
     { id: 'R-01', name: 'REQ must have verification', severity: 'error', evaluate: reqMustHaveVerification },
     { id: 'R-02', name: 'FUNC must satisfy REQ', severity: 'warning', evaluate: funcMustSatisfyReq },
@@ -925,6 +960,7 @@ export const V3_RULES = [
     { id: 'RD-04', name: 'Decomposition breadth', severity: 'warning', evaluate: decompositionBreadth },
     { id: 'MS-01', name: 'Milestone empty scope', severity: 'warning', evaluate: msEmptyScope },
     { id: 'MS-02', name: 'Milestone dangling dependency', severity: 'error', evaluate: msDanglingDependency },
+    { id: 'R-28', name: 'Ebenen-Präsenz (FLOW+SCHEMA when funcCount>1)', severity: 'warning', evaluate: ebenenPraesenz },
 ];
 /** Run all rules against a graph */
 export function evaluateRules(graph) {

package/dist/se/schema-quality-rules.d.ts

@@ -15,5 +15,6 @@
 import type { OntologyGraph } from './ontology.js';
 import type { RuleDefinition, RuleViolation } from './rules.js';
 export declare function sc02IsReferenced(graph: OntologyGraph): RuleViolation[];
+export declare function sc04FlowHasSchema(graph: OntologyGraph): RuleViolation[];
 export declare const SC_RULES: RuleDefinition[];
 export declare function evaluateSCRules(graph: OntologyGraph): RuleViolation[];

package/dist/se/schema-quality-rules.js

@@ -20,10 +20,37 @@ export function sc02IsReferenced(graph) {
     }));
 }
 // ---------------------------------------------------------------------------
+// SC-04: FLOW must reference a SCHEMA (CR-SM-226) — the sharp per-FLOW
+// inverse of SC-02. SC-02 catches an orphan SCHEMA (nobody uses it); SC-04
+// catches a FLOW with no data contract at all — until now only caught
+// loosely, around the SC-02-adjacent CDR completeness leg, never as its own
+// rule.
+// ---------------------------------------------------------------------------
+export function sc04FlowHasSchema(graph) {
+    const schemas = graph.elements.filter(e => e.type === 'SCHEMA');
+    return graph.elements
+        .filter(e => e.type === 'FLOW')
+        .filter(f => !graph.traces.some(t => t.source === f.id && t.type === 'relation' &&
+        graph.elements.some(e => e.id === t.target && e.type === 'SCHEMA')))
+        .map(f => ({
+        rule_id: 'SC-04',
+        severity: 'warning',
+        element_id: f.id,
+        message: `${f.id} has no SCHEMA binding`,
+        fix_hint: 'Link a SCHEMA via relation trace to define this FLOW\'s data contract',
+        context: {
+            element_type: f.type,
+            element_name: f.name,
+            candidate_targets: schemas.map(s => ({ id: s.id, type: s.type, name: s.name })),
+        },
+    }));
+}
+// ---------------------------------------------------------------------------
 // Aggregated array & convenience runner
 // ---------------------------------------------------------------------------
 export const SC_RULES = [
     { id: 'SC-02', name: 'Schema referenced by FLOW', severity: 'warning', evaluate: sc02IsReferenced },
+    { id: 'SC-04', name: 'FLOW has SCHEMA binding', severity: 'warning', evaluate: sc04FlowHasSchema },
 ];
 export function evaluateSCRules(graph) {
     return SC_RULES.flatMap(rule => rule.evaluate(graph));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sigloch/contracts",
-  "version": "2.0.0",
+  "version": "3.1.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",