@sigloch/contracts 3.0.0 → 3.1.0

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/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/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.22.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.22.0'; // CR-SM-226: +RULE_TO_PHASE (readiness.ts) — rule → SRR/PDR/CDR/TRR gate mapping analogous to RULE_TO_DIMENSION, exported PhaseGate enum, completeness-tested (no advisory fall-through); +DIMENSION_READINESS_NAME/PHASE_READINESS_NAME/DIMENSION_READINESS_DELTA_NAME Sprachregelung constants; -emergentPhase/-phaseScore (CR-120/146) DELETED from ReadinessReport — a third, undocumented phase construct next to RULE_TO_DIMENSION and the phase-gate grouping, no computation ever lived in contracts; +R-28 Ebenen-Präsenz (funcCount>1 requires ≥1 FLOW AND ≥1 SCHEMA, ONE combined rule — closes the vacuous-complete hole where 0 FLOWs/SCHEMAs read as "complete" because no per-element rule had anything to iterate) → PDR; +FC-04 FCHAIN-actor-bounded (ACTOR→FLOW→FUNC∈chain entry AND FUNC∈chain→FLOW→ACTOR exit, both required — stricter than FC-01's any-direction/UC-bypass check) → PDR; +SC-04 FLOW→SCHEMA sharp rule (every FLOW must relation→SCHEMA, the per-FLOW inverse of SC-02's per-SCHEMA check) → CDR; IO-01 extended to ALL FUNC pairs within an FCHAIN (removed the same-module skip — same-module pairs need an explicit FLOW just as much as cross-module ones) and added to RULE_TO_PHASE → PDR (was RULE_TO_DIMENSION-only); harness: +OP_RISK/isDestructiveOp/isStructuralOp destructive/structural classification per MutateCommand op (GVE-Audit F7) — informational only, does not drive the Apply-Gate verdict.
+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.js

@@ -81,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)
@@ -108,6 +113,12 @@ export const PhaseGate = z.enum(['SRR', 'PDR', 'CDR', 'TRR']);
  * 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',

package/package.json

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