@transitrix/diagrams 1.8.21 → 1.10.0

package/src/link-suspicion.ts

@@ -0,0 +1,181 @@
+// Link suspicion — methodology CONTRACT.md §16, reference implementation
+// `scripts/check-link-suspicion.mjs`. Pure: content-identity normalisation
+// (§16.1) and the suspicion verdict (§16.2 / §16.3's mechanical hatch) over
+// already-fetched file text. Git plumbing (finding the anchor commit,
+// reading a file at a ref) and the repo walk are IO and live in the CLI
+// (`src/repo-validate.ts`), same split as the rest of this package.
+//
+// Nothing here is stored: a caller re-derives the verdict on every check;
+// no file ever carries a `suspicious: true` flag (§16.2).
+
+// The administrative envelope (§16.1) — field names CONTRACT.md already
+// defines by name (§6 / §6.1 / §6.2 / §6.3 when present / §7). One list,
+// defined once; a spec revision that adds an envelope field extends this
+// list in the same revision rather than inventing a second mechanism.
+export const ENVELOPE_FIELDS = [
+  'zone', 'admitted_at', 'admitted_by', 'gate_checks', 'derived_from',
+  'admission_state', 'proposed_at', 'proposed_by', 'owner_to_confirm',
+  'rejected_at', 'rejected_by', 'rejection_reason',
+  'reviewer_authority',
+  'agreement', 'agreed_by', 'agreed_at',
+  'valid_from', 'valid_to',
+];
+
+function stripComment(line: string): string {
+  let inQuotes = false;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (ch === '"') inQuotes = !inQuotes;
+    else if (ch === '#' && !inQuotes) return line.slice(0, i);
+  }
+  return line;
+}
+
+/** Every non-blank, non-comment line of the file, except those belonging to
+ *  an `ENVELOPE_FIELDS` block (the key line and its more-indented
+ *  continuation lines), whitespace-normalised and sorted —
+ *  order-independent, formatting-independent, comment-independent. Not a
+ *  general YAML parser — a flat, line-oriented pass over the already-known
+ *  envelope field names, the same posture the methodology reference script
+ *  takes (its own header comment cites `baseline-manifest.mjs` /
+ *  `check-agreement.mjs` for precedent). */
+export function statementLines(text: string): string[] {
+  const kept: string[] = [];
+  let skipIndent: number | null = null;
+  for (const raw of text.split('\n')) {
+    const stripped = stripComment(raw).replace(/\s+$/, '');
+    if (!stripped.trim()) continue;
+    const indent = stripped.match(/^ */)?.[0].length ?? 0;
+    if (skipIndent !== null) {
+      if (indent > skipIndent) continue;
+      skipIndent = null;
+    }
+    const keyMatch = stripped.match(/^(\s*)([A-Za-z_][A-Za-z0-9_]*):/);
+    if (keyMatch && keyMatch[1].length === 0 && ENVELOPE_FIELDS.includes(keyMatch[2])) {
+      skipIndent = indent;
+      continue;
+    }
+    kept.push(stripped.trim().replace(/\s+/g, ' '));
+  }
+  return kept.sort();
+}
+
+function sameLines(a: string[], b: string[]): boolean {
+  return a.length === b.length && a.every((line, i) => line === b[i]);
+}
+
+export interface LineEdit {
+  from: string;
+  to: string;
+}
+
+/** A parsed `migrations/<slug>/TRANSFORM.yaml` manifest (§16.3). */
+export interface MigrationManifest {
+  slug: string;
+  mechanical: boolean;
+  appliesTo: string[];
+  lineEdits: LineEdit[];
+}
+
+function unquote(s: string): string {
+  const m = s.match(/^"(.*)"$/);
+  return m ? m[1] : s;
+}
+
+function normalizeEditLine(s: string): string {
+  return unquote(s.trim()).trim().replace(/\s+/g, ' ');
+}
+
+/** Minimal parse of the fixed `TRANSFORM.yaml` shape — `mechanical: true`,
+ *  `applies_to: [exact relative paths]`, `line_edits: [{from, to}]`. Not a
+ *  general YAML parser, same posture as {@link statementLines}. */
+export function parseMigrationManifest(text: string): Omit<MigrationManifest, 'slug'> {
+  const manifest: Omit<MigrationManifest, 'slug'> = { mechanical: false, appliesTo: [], lineEdits: [] };
+  let section: 'applies_to' | 'line_edits' | null = null;
+  let current: LineEdit | null = null;
+  for (const raw of text.split('\n')) {
+    const line = raw.replace(/\s+$/, '');
+    if (!line.trim() || line.trim().startsWith('#')) continue;
+
+    const topMatch = line.match(/^(\w+):\s*(.*)$/);
+    if (topMatch) {
+      const [, key, val] = topMatch;
+      if (key === 'mechanical') {
+        manifest.mechanical = val.trim() === 'true';
+        section = null;
+      } else if (key === 'applies_to') {
+        section = 'applies_to';
+      } else if (key === 'line_edits') {
+        section = 'line_edits';
+      }
+      continue;
+    }
+
+    if (section === 'applies_to') {
+      const m = line.match(/^\s*-\s*(.+)$/);
+      if (m) manifest.appliesTo.push(unquote(m[1].trim()));
+    } else if (section === 'line_edits') {
+      const fromMatch = line.match(/^\s*-\s*from:\s*(.+)$/);
+      if (fromMatch) {
+        current = { from: normalizeEditLine(fromMatch[1]), to: '' };
+        manifest.lineEdits.push(current);
+        continue;
+      }
+      const toMatch = line.match(/^\s*to:\s*(.+)$/);
+      if (toMatch && current) current.to = normalizeEditLine(toMatch[1]);
+    }
+  }
+  return manifest;
+}
+
+/** Replay a manifest's declared `lineEdits` against the before-state and
+ *  check the result matches the after-state exactly — the independent
+ *  verification §16.3 requires: the tool's `mechanical: true` declaration is
+ *  never trusted on its own; only a replay that reproduces the after-state
+ *  suppresses suspicion. */
+function replayExplains(beforeLines: string[], afterLines: string[], lineEdits: LineEdit[]): boolean {
+  const working = [...beforeLines];
+  for (const edit of lineEdits) {
+    const idx = working.indexOf(edit.from);
+    if (idx === -1) return false;
+    working.splice(idx, 1, edit.to);
+  }
+  return sameLines([...working].sort(), [...afterLines].sort());
+}
+
+export interface SuspicionResult {
+  suspicious: boolean;
+  /** True when a manifest declared `mechanical: true` for this target but
+   *  its replay did not fully explain the change — the hatch does not
+   *  self-grant; suspicion stands regardless of the flag (§16.3). */
+  hatchRefused?: boolean;
+}
+
+/**
+ * §16.2: *Suspicious* ⟺ the target's content identity at the anchor commit
+ * differs from its content identity now, **and** §16.3's hatch does not
+ * explain the difference.
+ *
+ * `beforeText` / `afterText` are already-fetched (git IO lives in the
+ * caller); `undefined` for either (no anchor, or the target no longer
+ * exists) means nothing to compare — not suspicious, per the reference
+ * script's `target-absent-at-anchor` / `target-absent-now` cases.
+ */
+export function checkSuspicion(
+  beforeText: string | undefined,
+  afterText: string | undefined,
+  applicableManifests: Array<Omit<MigrationManifest, 'slug'>> = [],
+): SuspicionResult {
+  if (beforeText === undefined || afterText === undefined) return { suspicious: false };
+
+  const beforeLines = statementLines(beforeText);
+  const afterLines = statementLines(afterText);
+  if (sameLines(beforeLines, afterLines)) return { suspicious: false };
+
+  for (const manifest of applicableManifests) {
+    if (replayExplains(beforeLines, afterLines, manifest.lineEdits)) {
+      return { suspicious: false };
+    }
+  }
+  return { suspicious: true, hatchRefused: applicableManifests.some((m) => m.mechanical) };
+}

package/src/metric/index.ts

@@ -0,0 +1,4 @@
+export type { Metric, MetricDirectionOfGood } from './types.js';
+export { METRIC_DIRECTIONS_OF_GOOD } from './types.js';
+export { validateMetric } from './validate.js';
+export type { MetricValidateOptions } from './validate.js';

package/src/metric/types.ts

@@ -0,0 +1,38 @@
+// METRIC — motivation-layer managed indicator (no ArchiMate counterpart).
+// Schema: methodology notations/ELEMENT_PRIMITIVES.md §7.27.
+
+import type { GateChecks } from '../requirement/types.js';
+
+/** How to read movement relative to `target` (§7.27). */
+export type MetricDirectionOfGood = 'higher_is_better' | 'lower_is_better' | 'on_target';
+
+export const METRIC_DIRECTIONS_OF_GOOD: readonly MetricDirectionOfGood[] = [
+  'higher_is_better',
+  'lower_is_better',
+  'on_target',
+];
+
+export interface Metric {
+  notation: 'metric';
+  id: string;
+  name: string;
+  /** Typed IDs of what this metric tracks — GOAL, CAPABILITY, or PROCESS. Non-empty. */
+  measures: string[];
+  /** Free-form unit the value and `target` are expressed in (percent, days, …). */
+  unit: string;
+  target: number;
+  direction_of_good: MetricDirectionOfGood;
+  /** ROLE-… accountable for tracking this metric and acting on it. */
+  owner_role: string;
+  description?: string;
+
+  // Admission record (CONTRACT.md §6).
+  zone: 'canon';
+  admitted_at: string;
+  admitted_by: string;
+  gate_checks: GateChecks;
+
+  // Primitive lifecycle (CONTRACT.md §7).
+  valid_from: string;
+  valid_to: string | null;
+}

package/src/metric/validate.ts

@@ -0,0 +1,102 @@
+// METRIC validator — methodology ELEMENT_PRIMITIVES.md §7.27 / §9.
+//
+// Codes:
+//   METRIC-001 — shape / id grammar / required envelope + per-type fields
+//               (measures, unit, target, direction_of_good, owner_role).
+//   METRIC-002 — measures is empty, or an entry does not resolve to an
+//               admitted GOAL / CAPABILITY / PROCESS in canon.
+//   METRIC-003 — direction_of_good outside {higher_is_better, lower_is_better,
+//               on_target}.
+//   METRIC-004 — owner_role does not resolve to an admitted ROLE in canon.
+//
+// Resolution rules (METRIC-002/004) that need artefact *existence* run only
+// when a `CanonCatalog` is supplied; the TYPE checks are derivable from the
+// id prefix and run either way.
+
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+import { typeOfId, isCanonicalIdOfType, type CanonCatalog } from '../typed-id.js';
+import { METRIC_DIRECTIONS_OF_GOOD } from './types.js';
+
+export interface MetricValidateOptions {
+  /** When provided, METRIC-002/004 enforce artefact existence for cross-refs. */
+  catalog?: CanonCatalog;
+}
+
+const MEASURES_TYPES = ['GOAL', 'CAPABILITY', 'PROCESS'] as const;
+
+export function validateMetric(input: unknown, options: MetricValidateOptions = {}): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    errors.push({ code: 'METRIC-001', message: 'Metric must be a YAML mapping.' });
+    return { valid: false, errors, warnings };
+  }
+  const m = input as Record<string, unknown>;
+
+  // METRIC-001 — id grammar + notation tag + envelope + plain per-type fields.
+  if (!isCanonicalIdOfType(m.id, 'METRIC')) {
+    errors.push({ code: 'METRIC-001', message: `id "${String(m.id)}" must match METRIC-[<middle>-]<INTEGER>.`, path: 'id' });
+  }
+  if (m.notation !== 'metric') {
+    errors.push({ code: 'METRIC-001', message: 'notation must be the fixed value "metric".', path: 'notation' });
+  }
+  if (m.zone !== 'canon') {
+    errors.push({ code: 'METRIC-001', message: 'zone is required and must be "canon".', path: 'zone' });
+  }
+  for (const f of ['name', 'admitted_at', 'admitted_by', 'valid_from', 'unit', 'owner_role'] as const) {
+    if (typeof m[f] !== 'string' || (m[f] as string).trim() === '') {
+      errors.push({ code: 'METRIC-001', message: `${f} is required.`, path: f });
+    }
+  }
+  if (m.gate_checks === null || typeof m.gate_checks !== 'object') {
+    errors.push({ code: 'METRIC-001', message: 'gate_checks is required and must be a mapping.', path: 'gate_checks' });
+  }
+  if (!('valid_to' in m) || !(typeof m.valid_to === 'string' || m.valid_to === null)) {
+    errors.push({ code: 'METRIC-001', message: 'valid_to is required (an ISO date string or null).', path: 'valid_to' });
+  }
+  if (typeof m.target !== 'number' || Number.isNaN(m.target)) {
+    errors.push({ code: 'METRIC-001', message: 'target is required and must be a number.', path: 'target' });
+  }
+
+  // direction_of_good — required (METRIC-001) + enum (METRIC-003).
+  const dir = m.direction_of_good;
+  if (dir === undefined || dir === null || dir === '') {
+    errors.push({ code: 'METRIC-001', message: 'direction_of_good is required.', path: 'direction_of_good' });
+  } else if (!(METRIC_DIRECTIONS_OF_GOOD as readonly string[]).includes(dir as string)) {
+    errors.push({
+      code: 'METRIC-003',
+      message: `direction_of_good "${String(dir)}" must be one of ${METRIC_DIRECTIONS_OF_GOOD.join(', ')}.`,
+      path: 'direction_of_good',
+    });
+  }
+
+  // measures — required non-empty list (METRIC-001), each resolves to GOAL/CAPABILITY/PROCESS (METRIC-002).
+  const measures = m.measures;
+  if (!Array.isArray(measures) || measures.length === 0) {
+    errors.push({ code: 'METRIC-001', message: 'measures is required and must be a non-empty list of typed IDs.', path: 'measures' });
+  } else {
+    measures.forEach((ref, i) => {
+      const type = typeOfId(ref);
+      if (!type || !(MEASURES_TYPES as readonly string[]).includes(type as typeof MEASURES_TYPES[number])) {
+        errors.push({ code: 'METRIC-002', message: `measures[${i}] "${String(ref)}" must resolve to a GOAL, CAPABILITY, or PROCESS.`, path: `measures[${i}]` });
+        return;
+      }
+      if (options.catalog && options.catalog.typeOf(ref as string) === undefined) {
+        errors.push({ code: 'METRIC-002', message: `measures[${i}] "${String(ref)}" does not resolve to an admitted artefact.`, path: `measures[${i}]` });
+      }
+    });
+  }
+
+  // owner_role — must be a typed ROLE id (METRIC-004), and resolve when a catalog is supplied.
+  const ownerRole = m.owner_role;
+  if (typeof ownerRole === 'string' && ownerRole.trim() !== '') {
+    if (!isCanonicalIdOfType(ownerRole, 'ROLE')) {
+      errors.push({ code: 'METRIC-004', message: `owner_role "${ownerRole}" must be a typed ROLE id.`, path: 'owner_role' });
+    } else if (options.catalog && options.catalog.typeOf(ownerRole) === undefined) {
+      errors.push({ code: 'METRIC-004', message: `owner_role "${ownerRole}" does not resolve to an admitted artefact.`, path: 'owner_role' });
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}

package/src/need/index.ts

@@ -0,0 +1,3 @@
+export type { Need } from './types.js';
+export { validateNeed } from './validate.js';
+export type { NeedValidateOptions } from './validate.js';

package/src/need/types.ts

@@ -0,0 +1,31 @@
+// NEED — motivation-layer stakeholder/user need (no ArchiMate counterpart).
+// Upstream of REQUIREMENT — schema: methodology notations/ELEMENT_PRIMITIVES.md §7.28.
+
+import type { GateChecks } from '../requirement/types.js';
+import type { AgreementValue } from '../agreement.js';
+
+export interface Need {
+  notation: 'need';
+  id: string;
+  name: string;
+  /** Typed ID of the STAKEHOLDER whose need this is. */
+  stakeholder: string;
+  description?: string;
+
+  // Agreement axis (CONTRACT.md §6.3, when present) — independent of admission.
+  /** `draft` \| `agreed` \| `disputed`. Absent ⇒ `agreed` (back-compat). */
+  agreement?: AgreementValue;
+  /** Required whenever `agreement` is present (AGREE-003). Written only by a human when `agreement: agreed` (AGREE-002). */
+  agreed_by?: string;
+  agreed_at?: string;
+
+  // Admission record (CONTRACT.md §6).
+  zone: 'canon';
+  admitted_at: string;
+  admitted_by: string;
+  gate_checks: GateChecks;
+
+  // Primitive lifecycle (CONTRACT.md §7).
+  valid_from: string;
+  valid_to: string | null;
+}

package/src/need/validate.ts

@@ -0,0 +1,71 @@
+// NEED validator — methodology ELEMENT_PRIMITIVES.md §7.28 / §9.
+//
+// Codes:
+//   NEED-001 — shape / id grammar / required envelope fields, including the
+//              required per-type `stakeholder` field.
+//   NEED-002 — stakeholder does not resolve to an admitted STAKEHOLDER in canon.
+//
+// The cross-cutting NEED-COVERAGE-001 / NEED-VALIDATION-COVERAGE-001..002
+// reverse-trace rules are owned elsewhere (CONTRACT.md §8, the compliance
+// reverse-index) and are out of scope for this single-artefact validator —
+// same posture as `validateRequirement` / `validateVerification`.
+//
+// Resolution (NEED-002 existence) runs only when a `CanonCatalog` is
+// supplied; the TYPE check is derivable from the id prefix and runs either way.
+
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+import { isCanonicalIdOfType, type CanonCatalog } from '../typed-id.js';
+import { checkAgreement } from '../agreement.js';
+
+export interface NeedValidateOptions {
+  /** When provided, NEED-002 enforces artefact existence for `stakeholder`. */
+  catalog?: CanonCatalog;
+}
+
+export function validateNeed(input: unknown, options: NeedValidateOptions = {}): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    errors.push({ code: 'NEED-001', message: 'Need must be a YAML mapping.' });
+    return { valid: false, errors, warnings };
+  }
+  const n = input as Record<string, unknown>;
+
+  // NEED-001 — id grammar + notation tag + envelope.
+  if (!isCanonicalIdOfType(n.id, 'NEED')) {
+    errors.push({ code: 'NEED-001', message: `id "${String(n.id)}" must match NEED-[<middle>-]<INTEGER>.`, path: 'id' });
+  }
+  if (n.notation !== 'need') {
+    errors.push({ code: 'NEED-001', message: 'notation must be the fixed value "need".', path: 'notation' });
+  }
+  if (n.zone !== 'canon') {
+    errors.push({ code: 'NEED-001', message: 'zone is required and must be "canon".', path: 'zone' });
+  }
+  for (const f of ['name', 'admitted_at', 'admitted_by', 'valid_from'] as const) {
+    if (typeof n[f] !== 'string' || (n[f] as string).trim() === '') {
+      errors.push({ code: 'NEED-001', message: `${f} is required.`, path: f });
+    }
+  }
+  if (n.gate_checks === null || typeof n.gate_checks !== 'object') {
+    errors.push({ code: 'NEED-001', message: 'gate_checks is required and must be a mapping.', path: 'gate_checks' });
+  }
+  if (!('valid_to' in n) || !(typeof n.valid_to === 'string' || n.valid_to === null)) {
+    errors.push({ code: 'NEED-001', message: 'valid_to is required (an ISO date string or null).', path: 'valid_to' });
+  }
+
+  // stakeholder — required (NEED-001) + resolves to STAKEHOLDER (NEED-002).
+  const stakeholder = n.stakeholder;
+  if (typeof stakeholder !== 'string' || stakeholder.trim() === '') {
+    errors.push({ code: 'NEED-001', message: 'stakeholder is required.', path: 'stakeholder' });
+  } else if (!isCanonicalIdOfType(stakeholder, 'STAKEHOLDER')) {
+    errors.push({ code: 'NEED-002', message: `stakeholder "${stakeholder}" must be a typed STAKEHOLDER id.`, path: 'stakeholder' });
+  } else if (options.catalog && options.catalog.typeOf(stakeholder) === undefined) {
+    errors.push({ code: 'NEED-002', message: `stakeholder "${stakeholder}" does not resolve to an admitted artefact.`, path: 'stakeholder' });
+  }
+
+  // AGREE-001..003 — agreement axis (CONTRACT.md §6.3.1), optional; absent ⇒ agreed.
+  errors.push(...checkAgreement(n));
+
+  return { valid: errors.length === 0, errors, warnings };
+}

package/src/repo-validate/check-candidate-fields.ts

@@ -0,0 +1,93 @@
+// Candidate-only fields on admitted canon — `ADMIT-009`.
+//
+// `ELEMENT_PRIMITIVES.md` §7.29 (methodology v3.6.0) states it normatively for
+// `RELEASE` and then generalises it to every TYPE:
+//
+//   > `RELEASE` has no `extraction_confidence` field — and neither does any
+//   > other canon element, of any TYPE. `extraction_confidence` is a review
+//   > flag on an ingest candidate (`candidate.extraction_confidence`,
+//   > vocabulary.yaml); it is surfaced in the review queue, drives
+//   > reviewer-authority routing (CONTRACT.md §6.2), and is never persisted
+//   > into canon. An admitted element carrying it is a defect in whatever
+//   > wrote it, not a precedent to follow.
+//
+// Nothing enforced that mechanically. The ingest pipeline that produces the
+// field lives in `methodology`'s `packages/ingest-cli` and only ever writes
+// *candidates*; admission into `canon/elements/**` happens in an adopter's own
+// tooling, which is `@transitrix/cli validate`'s side of the fence — so this is
+// where the rule has to bite.
+//
+// **Why the check keys on `zone`, not on the folder.** `extraction_confidence`
+// is legitimate on a candidate and meaningless — but not a defect — elsewhere;
+// only the *admitted* form is wrong. `zone: canon` is the admission marker
+// every standalone element carries (`ELEMENT_PRIMITIVES.md` §3, required
+// envelope field, `ELEM-001`), and it is the discriminator against the two
+// zones that may legitimately carry harvest metadata: `zone: field`, whose
+// provenance contract owns `source_quality` (CONTRACT.md §5/§11.2), and
+// `zone: codex`. Sidecars (`*.history.yaml`, `*.runstate.yaml`) carry no
+// `zone` and no `id`, so they fall out for free — the same "no id -> not an
+// element" split `docId` already makes for every sibling check in this folder.
+//
+// **Rule code.** Studio-authored as `ELEM-CANDIDATE-FIELD-001` (in the shape
+// methodology already uses for a named element-envelope rule outside the
+// numbered run — `ELEM-ALIAS-001`, `ELEM-FORMER-ID-001` — deliberately not
+// `ELEM-006`, since the numbered `ELEM-*` run is methodology's to extend and
+// squatting the next free number would collide with whatever it registers
+// there next). Renamed to `ADMIT-009` (transitrix/methodology#505, merged
+// 2026-08-19) now that methodology has registered a code of its own for
+// §7.29 — no functional change, this is that alias.
+
+import { docId } from './validate-repo.js';
+import type { RepoDoc, RepoFinding, RepoModelInput } from './types.js';
+
+const PScope: RepoFinding['scope'] = 'repo';
+
+/**
+ * Fields that belong to an ingest candidate and are never persisted into
+ * canon. Each entry names the field and the provenance pattern that replaces
+ * it, so the finding points at the correct shape rather than only failing
+ * closed. One entry today; the list is the extension point if methodology
+ * closes another candidate-side field out of canon the same way.
+ */
+const CANDIDATE_ONLY_FIELDS: readonly { field: string; instead: string }[] = [
+  {
+    field: 'extraction_confidence',
+    instead:
+      "cite the evidence through 'derived_from' (ELEMENT_PRIMITIVES.md §3) — " +
+      'an OBSERVATION or another Field/Codex artefact; the review flag stays on the ' +
+      'ingest candidate and is not carried across admission',
+  },
+];
+
+/** True when the doc is an admitted canon element — `zone: canon` per
+ *  `ELEMENT_PRIMITIVES.md` §3. Deliberately narrow: a doc with no `zone`
+ *  (a sidecar) or a non-canon zone (`field`, `codex`) is not admitted canon
+ *  and this rule says nothing about it. */
+function isAdmittedCanonElement(doc: RepoDoc): boolean {
+  return doc.data?.['zone'] === 'canon';
+}
+
+/**
+ * `ADMIT-009` — a candidate-only field present on an admitted (`zone: canon`)
+ * element, of any TYPE. Appends findings; pure, deterministic order.
+ */
+export function checkCandidateFields(input: RepoModelInput, findings: RepoFinding[]): void {
+  for (const doc of input.elements) {
+    if (!doc.data) continue;
+    if (!isAdmittedCanonElement(doc)) continue;
+
+    const id = docId(doc) ?? '';
+    for (const { field, instead } of CANDIDATE_ONLY_FIELDS) {
+      if (doc.data[field] === undefined) continue;
+      findings.push({
+        scope: PScope,
+        id,
+        ruleId: 'ADMIT-009',
+        message:
+          `ADMIT-009: admitted element '${id || doc.path}' carries '${field}', ` +
+          `which is an ingest-candidate review flag and is never persisted into canon ` +
+          `(ELEMENT_PRIMITIVES.md §7.29). Remove it and ${instead}.`,
+      });
+    }
+  }
+}

package/src/repo-validate/check-versioned-attributes.ts

@@ -0,0 +1,112 @@
+// Versioned-attribute sidecar checks (CONTRACT.md §9) — `VERSIONED-001..005`.
+//
+// A sidecar is any doc under `canon/elements/**` shaped like one (`target` +
+// `attribute_versions`, no `id` — same "no id -> not an element" convention
+// `docId` already uses to skip these docs everywhere else in this file's
+// sibling checks). Both halves of §9.3 live here:
+//   - VERSIONED-001 — a sidecar's `target` must resolve to an admitted
+//     primitive in this same model.
+//   - VERSIONED-002/003/005 — the sidecar's own array shape, delegated to
+//     the shared `../versioned-attribute` module (needs VERSIONED-005's
+//     bound: the target's own `valid_from`/`valid_to`, read from the
+//     resolved target doc).
+//   - VERSIONED-004 — a field declared `time_varying` present inline on its
+//     primitive, instead of only in the sidecar.
+//
+// `TIME_VARYING_FIELDS` is deliberately narrower than the full candidate
+// list in CONTRACT.md §9.4: it only enforces fields already `time_varying`
+// on methodology's *currently-merged* notation specs. `capability` covers
+// `current_maturity`, `target_maturity`, `owner_role`, `target_date` per
+// `05-capability-map.md` §13/§14. Applications-catalogue `maturity` (and its
+// sibling `owner_role`/`vendor`) is on the same 2026-08-02 maturity ADR but
+// is not enforced here yet — it lives on the `applications[]` list inside a
+// catalogue view document, not on a standalone element primitive, and this
+// check only walks `elements`.
+
+import { parseSidecar, validateSidecar } from '../versioned-attribute/index.js';
+import { docId } from './validate-repo.js';
+import type { RepoDoc, RepoFinding, RepoModelInput } from './types.js';
+
+const PScope: RepoFinding['scope'] = 'repo';
+
+const TIME_VARYING_FIELDS: Record<string, string[]> = {
+  capability: ['current_maturity', 'target_maturity', 'owner_role', 'target_date'],
+};
+
+function readString(data: Record<string, unknown>, key: string): string | undefined {
+  const v = data[key];
+  return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+
+/** VERSIONED-004 — a time_varying field present inline on its primitive. */
+function checkInlineTimeVarying(elements: RepoDoc[], findings: RepoFinding[]): void {
+  for (const doc of elements) {
+    if (!doc.data) continue;
+    const id = docId(doc);
+    if (!id) continue; // sidecars carry no id — not a primitive
+    const notation = doc.data['notation'];
+    if (typeof notation !== 'string') continue;
+    const fields = TIME_VARYING_FIELDS[notation];
+    if (!fields) continue;
+
+    for (const field of fields) {
+      if (doc.data[field] !== undefined) {
+        findings.push({
+          scope: PScope,
+          id,
+          ruleId: 'VERSIONED-004',
+          message:
+            `VERSIONED-004: '${id}' declares '${field}' inline; it is time_varying and belongs in ` +
+            `the sidecar '${id}.history.yaml' (CONTRACT.md §9), not on the primitive.`,
+        });
+      }
+    }
+  }
+}
+
+/** VERSIONED-001/002/003/005 — every sidecar doc found under `canon/elements/**`. */
+function checkSidecars(elements: RepoDoc[], findings: RepoFinding[]): void {
+  const elementById = new Map<string, RepoDoc>();
+  for (const doc of elements) {
+    const id = docId(doc);
+    if (id) elementById.set(id, doc);
+  }
+
+  for (const doc of elements) {
+    if (!doc.data || docId(doc)) continue; // sidecars have no id
+    const sidecar = parseSidecar(doc.data);
+    if (!sidecar) continue; // not shaped like a sidecar — ignore, same as docId's element/non-element split
+
+    const targetDoc = elementById.get(sidecar.target);
+    if (!targetDoc) {
+      findings.push({
+        scope: PScope,
+        id: sidecar.target,
+        ruleId: 'VERSIONED-001',
+        message: `VERSIONED-001: sidecar '${doc.path}' target '${sidecar.target}' does not resolve to an admitted primitive.`,
+      });
+      continue;
+    }
+
+    const targetValidFrom = targetDoc.data ? readString(targetDoc.data, 'valid_from') : undefined;
+    const validToRaw = targetDoc.data?.['valid_to'];
+    const targetValidTo = validToRaw === null ? null : typeof validToRaw === 'string' ? validToRaw : undefined;
+
+    for (const f of validateSidecar(sidecar, targetValidFrom, targetValidTo)) {
+      findings.push({
+        scope: PScope,
+        id: sidecar.target,
+        ruleId: f.code,
+        severity: f.severity,
+        message: `${f.code}: sidecar '${doc.path}' ${f.message}`,
+      });
+    }
+  }
+}
+
+/** Run the versioned-attribute sidecar checks (VERSIONED-001..005) over the
+ *  loaded element set and append findings. Pure, deterministic order. */
+export function checkVersionedAttributes(input: RepoModelInput, findings: RepoFinding[]): void {
+  checkInlineTimeVarying(input.elements, findings);
+  checkSidecars(input.elements, findings);
+}

package/src/repo-validate/validate-repo.ts

@@ -29,6 +29,8 @@
 
 import { checkStrategyChainSemantics } from './check-strategy-chain.js';
 import { checkElementHygiene } from './check-element-hygiene.js';
+import { checkVersionedAttributes } from './check-versioned-attributes.js';
+import { checkCandidateFields } from './check-candidate-fields.js';
 import type { RepoDoc, RepoFinding, RepoModelInput } from './types.js';
 
 const PScope: RepoFinding['scope'] = 'repo';
@@ -428,5 +430,10 @@ export function validateRepoModel(input: RepoModelInput): RepoFinding[] {
   // Phase 8 — standalone-element envelope rules ported from DSM's Go
   // Validate*Element functions (GOAL-ELEM-001..003, ACTION-001/002/005).
   checkElementHygiene(input, findings);
+  // Phase 9 — versioned-attribute sidecar rules (CONTRACT.md §9, VERSIONED-001..005).
+  checkVersionedAttributes(input, findings);
+  // Phase 10 — candidate-only fields on admitted canon (ELEMENT_PRIMITIVES.md
+  // §7.29, ADMIT-009).
+  checkCandidateFields(input, findings);
   return findings;
 }