@transitrix/diagrams 1.8.21 → 1.9.18

package/dist/link-suspicion.js

@@ -0,0 +1,156 @@
+// 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) {
+    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) {
+    const kept = [];
+    let skipIndent = 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, b) {
+    return a.length === b.length && a.every((line, i) => line === b[i]);
+}
+function unquote(s) {
+    const m = s.match(/^"(.*)"$/);
+    return m ? m[1] : s;
+}
+function normalizeEditLine(s) {
+    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) {
+    const manifest = { mechanical: false, appliesTo: [], lineEdits: [] };
+    let section = null;
+    let current = 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, afterLines, lineEdits) {
+    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());
+}
+/**
+ * §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, afterText, applicableManifests = []) {
+    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/dist/metric/index.d.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/dist/metric/index.js

@@ -0,0 +1,2 @@
+export { METRIC_DIRECTIONS_OF_GOOD } from './types.js';
+export { validateMetric } from './validate.js';

package/dist/metric/types.d.ts

@@ -0,0 +1,24 @@
+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 declare const METRIC_DIRECTIONS_OF_GOOD: readonly MetricDirectionOfGood[];
+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;
+    zone: 'canon';
+    admitted_at: string;
+    admitted_by: string;
+    gate_checks: GateChecks;
+    valid_from: string;
+    valid_to: string | null;
+}

package/dist/metric/types.js

@@ -0,0 +1,7 @@
+// METRIC — motivation-layer managed indicator (no ArchiMate counterpart).
+// Schema: methodology notations/ELEMENT_PRIMITIVES.md §7.27.
+export const METRIC_DIRECTIONS_OF_GOOD = [
+    'higher_is_better',
+    'lower_is_better',
+    'on_target',
+];

package/dist/metric/validate.d.ts

@@ -0,0 +1,7 @@
+import type { ValidationResult } from '../validation-types.js';
+import { type CanonCatalog } from '../typed-id.js';
+export interface MetricValidateOptions {
+    /** When provided, METRIC-002/004 enforce artefact existence for cross-refs. */
+    catalog?: CanonCatalog;
+}
+export declare function validateMetric(input: unknown, options?: MetricValidateOptions): ValidationResult;

package/dist/metric/validate.js

@@ -0,0 +1,90 @@
+// 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 { typeOfId, isCanonicalIdOfType } from '../typed-id.js';
+import { METRIC_DIRECTIONS_OF_GOOD } from './types.js';
+const MEASURES_TYPES = ['GOAL', 'CAPABILITY', 'PROCESS'];
+export function validateMetric(input, options = {}) {
+    const errors = [];
+    const warnings = [];
+    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;
+    // 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']) {
+        if (typeof m[f] !== 'string' || m[f].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.includes(dir)) {
+        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.includes(type)) {
+                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) === 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/dist/need/index.d.ts

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

package/dist/need/index.js

@@ -0,0 +1 @@
+export { validateNeed } from './validate.js';

package/dist/need/types.d.ts

@@ -0,0 +1,21 @@
+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;
+    /** `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;
+    zone: 'canon';
+    admitted_at: string;
+    admitted_by: string;
+    gate_checks: GateChecks;
+    valid_from: string;
+    valid_to: string | null;
+}

package/dist/need/types.js

@@ -0,0 +1,3 @@
+// NEED — motivation-layer stakeholder/user need (no ArchiMate counterpart).
+// Upstream of REQUIREMENT — schema: methodology notations/ELEMENT_PRIMITIVES.md §7.28.
+export {};

package/dist/need/validate.d.ts

@@ -0,0 +1,7 @@
+import type { ValidationResult } from '../validation-types.js';
+import { type CanonCatalog } from '../typed-id.js';
+export interface NeedValidateOptions {
+    /** When provided, NEED-002 enforces artefact existence for `stakeholder`. */
+    catalog?: CanonCatalog;
+}
+export declare function validateNeed(input: unknown, options?: NeedValidateOptions): ValidationResult;

package/dist/need/validate.js

@@ -0,0 +1,60 @@
+// 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 { isCanonicalIdOfType } from '../typed-id.js';
+import { checkAgreement } from '../agreement.js';
+export function validateNeed(input, options = {}) {
+    const errors = [];
+    const warnings = [];
+    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;
+    // 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']) {
+        if (typeof n[f] !== 'string' || n[f].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/dist/repo-validate/check-versioned-attributes.d.ts

@@ -0,0 +1,4 @@
+import type { RepoFinding, RepoModelInput } from './types.js';
+/** Run the versioned-attribute sidecar checks (VERSIONED-001..005) over the
+ *  loaded element set and append findings. Pure, deterministic order. */
+export declare function checkVersionedAttributes(input: RepoModelInput, findings: RepoFinding[]): void;

package/dist/repo-validate/check-versioned-attributes.js

@@ -0,0 +1,105 @@
+// 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';
+const PScope = 'repo';
+const TIME_VARYING_FIELDS = {
+    capability: ['current_maturity', 'target_maturity', 'owner_role', 'target_date'],
+};
+function readString(data, key) {
+    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, findings) {
+    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, findings) {
+    const elementById = new Map();
+    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, findings) {
+    checkInlineTimeVarying(input.elements, findings);
+    checkSidecars(input.elements, findings);
+}

package/dist/repo-validate/validate-repo.js

@@ -28,6 +28,7 @@
 // deferred per the ADR.
 import { checkStrategyChainSemantics } from './check-strategy-chain.js';
 import { checkElementHygiene } from './check-element-hygiene.js';
+import { checkVersionedAttributes } from './check-versioned-attributes.js';
 const PScope = 'repo';
 /** Statuses that, per lint.py's policy check, require an owner. */
 const OWNER_REQUIRED_STATUSES = new Set(['Active', 'Production']);
@@ -412,5 +413,7 @@ export function validateRepoModel(input) {
     // 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);
     return findings;
 }

package/dist/requirement/index.d.ts

@@ -1,4 +1,4 @@
-export type { Requirement, RequirementSeverity, GateChecks } from './types.js';
-export { REQUIREMENT_DERIVED_FROM_TYPES } from './types.js';
+export type { Requirement, RequirementSeverity, RequirementLevel, RequirementKind, GateChecks } from './types.js';
+export { REQUIREMENT_DERIVED_FROM_TYPES, REQUIREMENT_LEVELS, REQUIREMENT_KINDS } from './types.js';
 export { validateRequirement } from './validate.js';
 export type { RequirementValidateOptions } from './validate.js';

package/dist/requirement/index.js

@@ -1,2 +1,2 @@
-export { REQUIREMENT_DERIVED_FROM_TYPES } from './types.js';
+export { REQUIREMENT_DERIVED_FROM_TYPES, REQUIREMENT_LEVELS, REQUIREMENT_KINDS } from './types.js';
 export { validateRequirement } from './validate.js';

package/dist/requirement/types.d.ts

@@ -1,3 +1,4 @@
+import type { AgreementValue } from '../agreement.js';
 export type RequirementSeverity = 'high' | 'medium' | 'low';
 /** Standard canon admission gate checks (CONTRACT.md §6). */
 export interface GateChecks {
@@ -7,6 +8,12 @@ export interface GateChecks {
 }
 /** TYPEs a requirement may be derived from (15-requirement.md §2, REQ-003). */
 export declare const REQUIREMENT_DERIVED_FROM_TYPES: readonly ["LAW", "REGULATION", "POLICY", "INTERNAL_STANDARD"];
+/** ISO/IEC/IEEE 29148 specification-tier ladder (15-requirement.md §2.5, REQ-005). */
+export type RequirementLevel = 'stakeholder' | 'system' | 'software';
+export declare const REQUIREMENT_LEVELS: readonly RequirementLevel[];
+/** Functional vs quality classification (15-requirement.md §2.6, REQ-006). */
+export type RequirementKind = 'functional' | 'quality';
+export declare const REQUIREMENT_KINDS: readonly RequirementKind[];
 export interface Requirement {
     notation: 'requirement';
     id: string;
@@ -14,8 +21,19 @@ export interface Requirement {
     description: string;
     /** Organisation-defined priority. */
     severity?: RequirementSeverity;
+    /** ISO/IEC/IEEE 29148 specification tier (§2.5, REQ-005). */
+    level?: RequirementLevel;
+    /** Functional vs quality classification (§2.6, REQ-006). */
+    kind?: RequirementKind;
     /** Typed IDs of the codex source documents this requirement is drawn from. */
     derived_from?: string[];
+    /** Typed ID of the upstream NEED this requirement traces to (§2.7, REQ-SERVES-001). Optional, singular. */
+    serves?: string;
+    /** `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;
     zone: 'canon';
     admitted_at: string;
     admitted_by: string;

package/dist/requirement/types.js

@@ -2,3 +2,5 @@
 // Schema: methodology notations/elements/15-requirement.md §2.
 /** TYPEs a requirement may be derived from (15-requirement.md §2, REQ-003). */
 export const REQUIREMENT_DERIVED_FROM_TYPES = ['LAW', 'REGULATION', 'POLICY', 'INTERNAL_STANDARD'];
+export const REQUIREMENT_LEVELS = ['stakeholder', 'system', 'software'];
+export const REQUIREMENT_KINDS = ['functional', 'quality'];

package/dist/requirement/validate.js

@@ -9,7 +9,8 @@
 // supplied; the TYPE check (REQ-003) is derivable from the id prefix and runs
 // either way.
 import { typeOfId, isCanonicalIdOfType } from '../typed-id.js';
-import { REQUIREMENT_DERIVED_FROM_TYPES } from './types.js';
+import { checkAgreement } from '../agreement.js';
+import { REQUIREMENT_DERIVED_FROM_TYPES, REQUIREMENT_LEVELS, REQUIREMENT_KINDS } from './types.js';
 const REQUIRED_FIELDS = [
     'notation', 'name', 'description', 'zone', 'admitted_at', 'admitted_by', 'gate_checks', 'valid_from',
 ];
@@ -77,5 +78,25 @@ export function validateRequirement(input, options = {}) {
             });
         }
     }
+    // REQ-005 — level closed vocabulary (optional; only checked when present).
+    if (r.level !== undefined && !REQUIREMENT_LEVELS.includes(r.level)) {
+        errors.push({ code: 'REQ-005', message: `level "${String(r.level)}" must be one of ${REQUIREMENT_LEVELS.join(', ')}.`, path: 'level' });
+    }
+    // REQ-006 — kind closed vocabulary (optional; only checked when present).
+    if (r.kind !== undefined && !REQUIREMENT_KINDS.includes(r.kind)) {
+        errors.push({ code: 'REQ-006', message: `kind "${String(r.kind)}" must be one of ${REQUIREMENT_KINDS.join(', ')}.`, path: 'kind' });
+    }
+    // REQ-SERVES-001 — serves resolves to an admitted NEED (optional, singular).
+    if (r.serves !== undefined) {
+        const serves = r.serves;
+        if (typeof serves !== 'string' || serves.trim() === '' || typeOfId(serves) !== 'NEED') {
+            errors.push({ code: 'REQ-SERVES-001', message: `serves "${String(serves)}" must be a typed NEED id.`, path: 'serves' });
+        }
+        else if (options.catalog && options.catalog.typeOf(serves) === undefined) {
+            errors.push({ code: 'REQ-SERVES-001', message: `serves "${serves}" does not resolve to an admitted NEED.`, path: 'serves' });
+        }
+    }
+    // AGREE-001..003 — agreement axis (CONTRACT.md §6.3.1), optional; absent ⇒ agreed.
+    errors.push(...checkAgreement(r));
     return { valid: errors.length === 0, errors, warnings };
 }

package/dist/risk/index.d.ts

@@ -0,0 +1,4 @@
+export type { Risk, RiskLevel } from './types.js';
+export { RISK_LEVELS } from './types.js';
+export { validateRisk } from './validate.js';
+export type { RiskValidateOptions } from './validate.js';

package/dist/risk/index.js

@@ -0,0 +1,2 @@
+export { RISK_LEVELS } from './types.js';
+export { validateRisk } from './validate.js';