yarramate 1.33.0 → 1.34.0

package/catalogues/core-enrichment.yaml

@@ -900,6 +900,146 @@ questions:
     resolution: >-
       Give the person a letter (an owner claim on what they answer for, or a
       responsible, consulted or informed relationship) or retire the subject.
+  - id: risk-threatens-nothing
+    wave: motivation
+    since: "1.34"
+    scope: subject
+    subjects:
+      kinds:
+        - yarramate/policy@0.3#risk
+      statuses:
+        - planned
+        - current
+    trigger:
+      - condition: missing-linkage
+        kinds:
+          - yarramate/core@0.1#influence
+        direction: outgoing
+        counterpartKinds:
+          - yarramate/core@0.1#goal
+          - yarramate/core@0.1#requirement
+          - yarramate/core@0.1#constraint
+    question: >-
+      What does {subject.name} threaten?
+    askPlain: >-
+      If "{subject.name}" comes true, which goal, requirement or constraint
+      takes the hit?
+    materiality: >-
+      A risk that threatens nothing named cannot be prioritised or retired:
+      its severity has nothing to be measured against, and nobody can say
+      when it has passed.
+    authority: either
+    resolution: >-
+      Add an `influence` relationship from the risk to the goal, requirement
+      or constraint it threatens.
+  - id: risk-unmitigated
+    wave: motivation
+    since: "1.34"
+    scope: subject
+    subjects:
+      kinds:
+        - yarramate/policy@0.3#risk
+      statuses:
+        - current
+    trigger:
+      - condition: missing-linkage
+        kinds:
+          - yarramate/core@0.1#influence
+          - yarramate/core@0.1#association
+        direction: incoming
+        counterpartKinds:
+          - yarramate/core@0.1#workPackage
+          - yarramate/core@0.1#deliverable
+          - yarramate/core@0.1#constraint
+          - yarramate/core@0.1#courseOfAction
+    question: >-
+      What mitigates {subject.name}?
+    askPlain: >-
+      "{subject.name}" is live. What work, deliverable, rule or decision is in
+      place to reduce it?
+    materiality: >-
+      A live risk with no mitigation is a bet the engagement is making without
+      saying so; the log exists to make that visible.
+    authority: either
+    resolution: >-
+      Add an `influence` relationship from the work package, deliverable,
+      constraint or decision that mitigates it to the risk, or retire the risk.
+  - id: risk-unowned
+    wave: motivation
+    since: "1.34"
+    scope: subject
+    subjects:
+      kinds:
+        - yarramate/policy@0.3#risk
+      statuses:
+        - planned
+        - current
+    trigger:
+      - condition: missing-claim
+        predicate: yarramate/ownership/owner
+    question: >-
+      Who owns {subject.name}?
+    askPlain: >-
+      Whose name is on "{subject.name}": who reviews it and decides when it
+      has passed?
+    materiality: >-
+      The risk owner is who a review date is asked of; without one,
+      risk-reviewed has no authority to sign it.
+    authority: either
+    resolution: >-
+      Add an owner reference to the actor or role that carries the risk.
+  - id: assumption-unconfirmed
+    wave: motivation
+    since: "1.34"
+    scope: subject
+    subjects:
+      kinds:
+        - yarramate/policy@0.3#assumption
+      statuses:
+        - planned
+        - current
+    trigger:
+      - condition: missing-attestation
+        topic: assumption-confirmed
+    question: >-
+      Has anyone confirmed {subject.name}?
+    askPlain: >-
+      "{subject.name}" is being built on. Has the person who can confirm it
+      said so, and when?
+    materiality: >-
+      An unconfirmed assumption is a risk wearing a calmer name; the
+      confirmation, with its date, is what turns it into a fact the delivery
+      can rest on.
+    authority: human
+    resolution: >-
+      Record an `assumption-confirmed` attestation by the role or actor that
+      can confirm it, dated; or retire the assumption.
+  - id: assumption-bears-on-nothing
+    wave: motivation
+    since: "1.34"
+    scope: subject
+    subjects:
+      kinds:
+        - yarramate/policy@0.3#assumption
+      statuses:
+        - planned
+        - current
+    trigger:
+      - condition: missing-relationship
+        kinds:
+          - yarramate/core@0.1#association
+        direction: outgoing
+    question: >-
+      What does {subject.name} bear on?
+    askPlain: >-
+      If "{subject.name}" turned out false, what in this design would change?
+    materiality: >-
+      An assumption that bears on nothing named is either decorative or
+      missing its edges, and the log cannot say which.
+    authority: either
+    resolution: >-
+      Add an `association` relationship from the assumption to the goal,
+      requirement, constraint or subject it bears on, or retire it.
   - id: actor-unassigned
     wave: business
     since: "0.1"

package/dist/adapters/mcp-cli.js

@@ -149,7 +149,7 @@ const runExport = (input, tool, root) => {
         };
     }
     // A text kind under `out`: markdown and graph are one file, rtm,
-    // responsibility and briefs a directory, as the CLI lays them out.
+    // responsibility, governance and briefs a directory, as the CLI lays them out.
     if (kind === 'markdown' || kind === 'graph') {
         mkdirSync(dirname(target), { recursive: true });
         writeFileSync(target, outcome.text, 'utf8');
@@ -172,6 +172,19 @@ const runExport = (input, tool, root) => {
             stderr: '',
         };
     }
+    if (kind === 'governance') {
+        const result = outcome.result;
+        mkdirSync(target, { recursive: true });
+        writeFileSync(join(target, 'GOVERNANCE.md'), outcome.text, 'utf8');
+        if (result !== undefined) {
+            writeFileSync(join(target, 'governance.json'), `${JSON.stringify(result.log, null, 2)}\n`, 'utf8');
+        }
+        return {
+            exitCode: 0,
+            stdout: `Wrote GOVERNANCE.md and governance.json to ${out}\n`,
+            stderr: '',
+        };
+    }
     if (kind === 'responsibility') {
         const result = outcome.result;
         mkdirSync(target, { recursive: true });

package/dist/brief.js

@@ -1,5 +1,5 @@
 import { conceptKinds } from './profile.js';
-import { EXTENSION_READING, RELATIONSHIP_READING, humanizeKind } from './relationship-reading.js';
+import { EXTENSION_READING, RELATIONSHIP_READING, contextualReading, humanizeKind } from './relationship-reading.js';
 const coreKindNames = new Map(conceptKinds.map(({ id, name }) => [id, name]));
 const motivationKindIds = new Set(conceptKinds
     .filter(({ layer }) => layer === 'motivation')
@@ -110,8 +110,18 @@ workspaceClaims) {
         if (claim === undefined || !('ref' in claim.object))
             continue;
         const description = claimValue(result.claims, subject.id, 'yarramate/relationship/description');
+        const coreKind = coreLocalKind(claim.predicate, profileContext?.relationshipKindLineages);
+        // A reading the endpoints decide (ADR 0160) speaks before the kind's own.
+        const endpointLineage = (id) => {
+            const kind = claimValue(result.claims, id, 'yarramate/concept/kind');
+            return kind === undefined ? undefined : profileContext?.conceptKindLineages.get(kind);
+        };
+        const contextual = coreKind === undefined
+            ? undefined
+            : contextualReading(endpointLineage(claim.subject), endpointLineage(claim.object.ref), coreKind);
         const entry = {
-            phrase: relationshipPhrase(coreLocalKind(claim.predicate, profileContext?.relationshipKindLineages), claim.predicate, claimValue(result.claims, subject.id, 'yarramate/access/mode'), claimValue(result.claims, subject.id, 'yarramate/flow/content')),
+            phrase: contextual ??
+                relationshipPhrase(coreKind, claim.predicate, claimValue(result.claims, subject.id, 'yarramate/access/mode'), claimValue(result.claims, subject.id, 'yarramate/flow/content')),
             target: claim.object.ref,
             ...(description === undefined ? {} : { description }),
         };

package/dist/cli-support.d.ts

@@ -7,7 +7,7 @@ export interface CliResult {
 export declare const isMainModule: (moduleUrl: string, entrypoint: string | undefined) => boolean;
 export declare const packageVersion: string;
 export declare const versionResult: (binary: string) => CliResult;
-export declare const usage = "Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate design <workspace.yaml> [--subject <subject-id>] [--catalogue <catalogue.yaml>] [--facilitate] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> \"<free text>\" | <subject-id> ... | <projection.yaml> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate ask <workspace.yaml> --subjects [--kind <term>] [--status <status>] [--json]\n  yarramate ask <workspace.yaml> --kinds [--json]\n  yarramate ask <workspace.yaml> --advise \"<topic>\" [--budget <tokens>] [--neighbours <n>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --where \"<free text>\" | <subject-id> ... [--json]\n  yarramate ask <workspace.yaml> --next [--json]\n  yarramate ask <workspace.yaml> --open [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --compare <from-state> <to-state> [--json]\n  yarramate ask <workspace.yaml> --changed <git-range> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml> [--json | --text]\n  yarramate export graph <workspace.yaml> [--out <file>]\n  yarramate export markdown <projection.yaml> <workspace.yaml> [--out <file>]\n  yarramate export markdown --changed <git-range> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export briefs --changed <git-range> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export rtm <workspace.yaml> --out <directory>\n  yarramate export responsibility <projection.yaml> <workspace.yaml> --out <directory>\n  yarramate export xlsx <projection.yaml> <workspace.yaml> --out <file>\n  yarramate import xlsx <workbook.xlsx> <workspace.yaml> [--json]\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml> [--changed <git-range>]\n";
+export declare const usage = "Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate design <workspace.yaml> [--subject <subject-id>] [--catalogue <catalogue.yaml>] [--facilitate] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> \"<free text>\" | <subject-id> ... | <projection.yaml> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate ask <workspace.yaml> --subjects [--kind <term>] [--status <status>] [--json]\n  yarramate ask <workspace.yaml> --kinds [--json]\n  yarramate ask <workspace.yaml> --advise \"<topic>\" [--budget <tokens>] [--neighbours <n>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --where \"<free text>\" | <subject-id> ... [--json]\n  yarramate ask <workspace.yaml> --next [--json]\n  yarramate ask <workspace.yaml> --open [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --compare <from-state> <to-state> [--json]\n  yarramate ask <workspace.yaml> --changed <git-range> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml> [--json | --text]\n  yarramate export graph <workspace.yaml> [--out <file>]\n  yarramate export markdown <projection.yaml> <workspace.yaml> [--out <file>]\n  yarramate export markdown --changed <git-range> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export briefs --changed <git-range> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export rtm <workspace.yaml> --out <directory>\n  yarramate export responsibility <projection.yaml> <workspace.yaml> --out <directory>\n  yarramate export governance <workspace.yaml> --out <directory>\n  yarramate export xlsx <projection.yaml> <workspace.yaml> --out <file>\n  yarramate import xlsx <workbook.xlsx> <workspace.yaml> [--json]\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml> [--changed <git-range>]\n";
 export declare const diagnosticJson: (diagnostics: unknown) => string;
 export declare const checkResultJson: (ok: boolean, diagnostics: unknown, counted?: {
     readonly documents: number;

package/dist/cli-support.js

@@ -22,7 +22,7 @@ export const versionResult = (binary) => ({
     stdout: `${binary} ${packageVersion}\n`,
     stderr: '',
 });
-export const usage = 'Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate design <workspace.yaml> [--subject <subject-id>] [--catalogue <catalogue.yaml>] [--facilitate] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> "<free text>" | <subject-id> ... | <projection.yaml> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate ask <workspace.yaml> --subjects [--kind <term>] [--status <status>] [--json]\n  yarramate ask <workspace.yaml> --kinds [--json]\n  yarramate ask <workspace.yaml> --advise "<topic>" [--budget <tokens>] [--neighbours <n>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --where "<free text>" | <subject-id> ... [--json]\n  yarramate ask <workspace.yaml> --next [--json]\n  yarramate ask <workspace.yaml> --open [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --compare <from-state> <to-state> [--json]\n  yarramate ask <workspace.yaml> --changed <git-range> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml> [--json | --text]\n  yarramate export graph <workspace.yaml> [--out <file>]\n  yarramate export markdown <projection.yaml> <workspace.yaml> [--out <file>]\n  yarramate export markdown --changed <git-range> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export briefs --changed <git-range> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export rtm <workspace.yaml> --out <directory>\n  yarramate export responsibility <projection.yaml> <workspace.yaml> --out <directory>\n  yarramate export xlsx <projection.yaml> <workspace.yaml> --out <file>\n  yarramate import xlsx <workbook.xlsx> <workspace.yaml> [--json]\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml> [--changed <git-range>]\n';
+export const usage = 'Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate design <workspace.yaml> [--subject <subject-id>] [--catalogue <catalogue.yaml>] [--facilitate] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> "<free text>" | <subject-id> ... | <projection.yaml> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate ask <workspace.yaml> --subjects [--kind <term>] [--status <status>] [--json]\n  yarramate ask <workspace.yaml> --kinds [--json]\n  yarramate ask <workspace.yaml> --advise "<topic>" [--budget <tokens>] [--neighbours <n>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --where "<free text>" | <subject-id> ... [--json]\n  yarramate ask <workspace.yaml> --next [--json]\n  yarramate ask <workspace.yaml> --open [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --compare <from-state> <to-state> [--json]\n  yarramate ask <workspace.yaml> --changed <git-range> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml> [--json | --text]\n  yarramate export graph <workspace.yaml> [--out <file>]\n  yarramate export markdown <projection.yaml> <workspace.yaml> [--out <file>]\n  yarramate export markdown --changed <git-range> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export briefs --changed <git-range> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export rtm <workspace.yaml> --out <directory>\n  yarramate export responsibility <projection.yaml> <workspace.yaml> --out <directory>\n  yarramate export governance <workspace.yaml> --out <directory>\n  yarramate export xlsx <projection.yaml> <workspace.yaml> --out <file>\n  yarramate import xlsx <workbook.xlsx> <workspace.yaml> [--json]\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml> [--changed <git-range>]\n';
 export const diagnosticJson = (diagnostics) => `${JSON.stringify({
     format: 'yarramate/diagnostic-result/v1',
     diagnostics,

package/dist/export-command.js

@@ -8,7 +8,7 @@ import { humanDiagnostics, usage, } from './cli-support.js';
 import { evaluateProjection, renderProjectionMarkdown } from './projection.js';
 import { createFileSystemStore } from './source-store.js';
 import { posixDirectoryOf } from './apply-command.js';
-import { briefsFromResult, exportBriefs, exportGraph, exportMarkdown, exportResponsibility, exportRtm, exportWorkbook, } from './tools/export.js';
+import { briefsFromResult, exportBriefs, exportGraph, exportMarkdown, exportGovernance, exportResponsibility, exportRtm, exportWorkbook, } from './tools/export.js';
 import { compileOf, readSource, } from './tools/workspace.js';
 import { loadWorkspaceManifest } from './workspace.js';
 // Every kind is derived in `tools/export.ts` (ADR 0156): this command
@@ -76,6 +76,7 @@ export function runExportCommand(options, cwd) {
             'briefs',
             'rtm',
             'responsibility',
+            'governance',
             'likec4',
             'xlsx',
         ].includes(kind)) {
@@ -121,20 +122,19 @@ export function runExportCommand(options, cwd) {
         };
     }
     const usesChanged = parsed.changed !== undefined;
-    const expectedPositionals = kind === 'graph' || kind === 'rtm' || usesChanged ? 1 : 2;
+    const wholeWorkspace = kind === 'graph' || kind === 'rtm' || kind === 'governance';
+    const expectedPositionals = wholeWorkspace || usesChanged ? 1 : 2;
     const workspacePath = parsed.positionals[expectedPositionals - 1];
-    const projectionPath = kind === 'graph' || kind === 'rtm' || usesChanged
-        ? undefined
-        : parsed.positionals[0];
+    const projectionPath = wholeWorkspace || usesChanged ? undefined : parsed.positionals[0];
     if (parsed.positionals.length !== expectedPositionals ||
         workspacePath === undefined ||
         parsed.json ||
-        (usesChanged &&
-            (kind === 'graph' || kind === 'rtm' || kind === 'responsibility')) ||
+        (usesChanged && (wholeWorkspace || kind === 'responsibility')) ||
         (parsed.budget !== undefined && kind !== 'briefs') ||
         ((kind === 'briefs' ||
             kind === 'rtm' ||
             kind === 'responsibility' ||
+            kind === 'governance' ||
             kind === 'xlsx') &&
             parsed.out === undefined)) {
         return { exitCode: 2, stdout: '', stderr: usage };
@@ -183,6 +183,20 @@ export function runExportCommand(options, cwd) {
                 stderr: '',
             };
         }
+        if (kind === 'governance') {
+            const exported = exportGovernance(tool);
+            if (!exported.ok)
+                return failedTool(exported);
+            const { markdown, log } = exported.result;
+            writeText(join(parsed.out, 'GOVERNANCE.md'), markdown);
+            writeText(join(parsed.out, 'governance.json'), `${JSON.stringify(log, null, 2)}\n`);
+            const gaps = log.summary.unowned + log.summary.unmitigated + log.summary.unconfirmed + log.summary.unreviewed;
+            return {
+                exitCode: 0,
+                stdout: `Wrote GOVERNANCE.md and governance.json (${log.summary.rows} row${log.summary.rows === 1 ? '' : 's'}, ${gaps} gap${gaps === 1 ? '' : 's'}) to ${parsed.out}\n`,
+                stderr: '',
+            };
+        }
         if (kind === 'responsibility') {
             const exported = exportResponsibility(tool, projectionPath);
             if (!exported.ok)

package/dist/governance-kinds.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The governance concept kinds (#560, ADR 0160): `yarramate/policy@0.3#risk`
+ * and `#assumption`, each a subkind of core `assessment`. A decision is the
+ * adopter's trial kind under `courseOfAction` until the trial reports, so
+ * it is not here. Review dates are attestations on the shipped topics
+ * below. Pure, so the canvas projection, the log builder and the brief read
+ * one table.
+ */
+export declare const GOVERNANCE_PROFILE = "yarramate/policy@0.3";
+export type GovernanceType = 'risk' | 'assumption';
+export declare const GOVERNANCE_KINDS: Readonly<Record<GovernanceType, string>>;
+/**
+ * The attestation topic that records a review of each type: a risk owner
+ * or the client role attests `risk-reviewed` on a risk, and the client
+ * confirms an assumption with `assumption-confirmed`. How old is too old is
+ * the adopter's threshold, not the engine's.
+ */
+export declare const REVIEW_TOPICS: Readonly<Record<GovernanceType, string>>;
+/**
+ * Whether a concept kind is a risk or an assumption, read through its
+ * lineage (ancestor-first) so a profile's own subkind counts; null for
+ * every other kind.
+ */
+export declare const governanceTypeOf: (lineage: readonly string[] | undefined, kind: string) => GovernanceType | null;

package/dist/governance-kinds.js

@@ -0,0 +1,40 @@
+/**
+ * The governance concept kinds (#560, ADR 0160): `yarramate/policy@0.3#risk`
+ * and `#assumption`, each a subkind of core `assessment`. A decision is the
+ * adopter's trial kind under `courseOfAction` until the trial reports, so
+ * it is not here. Review dates are attestations on the shipped topics
+ * below. Pure, so the canvas projection, the log builder and the brief read
+ * one table.
+ */
+export const GOVERNANCE_PROFILE = 'yarramate/policy@0.3';
+export const GOVERNANCE_KINDS = {
+    risk: `${GOVERNANCE_PROFILE}#risk`,
+    assumption: `${GOVERNANCE_PROFILE}#assumption`,
+};
+/**
+ * The attestation topic that records a review of each type: a risk owner
+ * or the client role attests `risk-reviewed` on a risk, and the client
+ * confirms an assumption with `assumption-confirmed`. How old is too old is
+ * the adopter's threshold, not the engine's.
+ */
+export const REVIEW_TOPICS = {
+    risk: 'risk-reviewed',
+    assumption: 'assumption-confirmed',
+};
+const TYPE_BY_KIND = {
+    [GOVERNANCE_KINDS.risk]: 'risk',
+    [GOVERNANCE_KINDS.assumption]: 'assumption',
+};
+/**
+ * Whether a concept kind is a risk or an assumption, read through its
+ * lineage (ancestor-first) so a profile's own subkind counts; null for
+ * every other kind.
+ */
+export const governanceTypeOf = (lineage, kind) => {
+    for (const member of lineage ?? [kind]) {
+        const type = TYPE_BY_KIND[member];
+        if (type !== undefined)
+            return type;
+    }
+    return TYPE_BY_KIND[kind] ?? null;
+};

package/dist/governance.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The governance log (#560, ADR 0160): the RAID log's risks and
+ * assumptions as the model holds them, derived the way the responsibility
+ * matrix is derived and never authored. One row per risk or assumption:
+ * its owner and status, what it threatens or bears on, what mitigates it,
+ * the latest review attestation, what it supersedes, and the groupings it
+ * aggregates into (an adopter's severity or likelihood classes, which the
+ * engine carries without knowing the scale). Issues and open questions are
+ * the adopter's and the interrogation's; the engine never sees an issue.
+ *
+ * Deterministic: identical inputs give identical bytes, so CI can diff it.
+ */
+import type { ResolvedProfileContext, SemanticGraph } from './compiler.js';
+import { type GovernanceType } from './governance-kinds.js';
+export interface GovernanceSource {
+    readonly path: string;
+    readonly line: number;
+}
+export interface GovernanceRef {
+    readonly id: string;
+    readonly name: string;
+}
+/** The latest review attestation on a row, by date. */
+export interface GovernanceReview {
+    readonly topic: string;
+    readonly on: string;
+    readonly by: string;
+    readonly source: GovernanceSource;
+}
+export interface GovernanceRow {
+    readonly subject: string;
+    readonly name: string;
+    readonly kind: string;
+    readonly type: GovernanceType;
+    readonly status: string | null;
+    readonly description?: string;
+    readonly owner: GovernanceRef | null;
+    /** A risk's outgoing `influence` targets: what it threatens. */
+    readonly threatens: readonly GovernanceRef[];
+    /** An assumption's outgoing `association` targets: what it bears on. */
+    readonly bearsOn: readonly GovernanceRef[];
+    /** Incoming `influence` or `association` sources on a risk: what mitigates it. */
+    readonly mitigatedBy: readonly GovernanceRef[];
+    readonly review: GovernanceReview | null;
+    readonly supersedes: readonly string[];
+    /** The groupings that aggregate this row: an adopter's rating classes. */
+    readonly groupedBy: readonly GovernanceRef[];
+}
+export interface GovernanceLog {
+    readonly format: 'yarramate/governance/v1';
+    readonly workspace: string;
+    readonly summary: {
+        readonly rows: number;
+        readonly risks: number;
+        readonly assumptions: number;
+        readonly unowned: number;
+        readonly unmitigated: number;
+        readonly unconfirmed: number;
+        readonly unreviewed: number;
+    };
+    readonly rows: readonly GovernanceRow[];
+    readonly gaps: {
+        /** Rows with no owner. */
+        readonly unowned: readonly string[];
+        /** Current risks nothing mitigates. */
+        readonly unmitigated: readonly string[];
+        /** Assumptions with no `assumption-confirmed` attestation. */
+        readonly unconfirmed: readonly string[];
+        /** Risks with no `risk-reviewed` attestation. How old is too old is the adopter's. */
+        readonly unreviewed: readonly string[];
+    };
+}
+export interface GovernanceOptions {
+    /** The subjects that may get a row; absent, every risk and assumption. */
+    readonly rows?: readonly string[];
+}
+export declare function buildGovernanceLog(workspace: string, graph: SemanticGraph, profileContext: ResolvedProfileContext, options?: GovernanceOptions): GovernanceLog;
+/** The log as one markdown table a person reads, with the gaps under it. */
+export declare function renderGovernanceMarkdown(log: GovernanceLog): string;

package/dist/governance.js

@@ -0,0 +1,164 @@
+import { ATTESTATION_PREDICATE_PREFIX, parseAttestationClaimValue, } from './graph-claims.js';
+import { REVIEW_TOPICS, governanceTypeOf, } from './governance-kinds.js';
+const CORE = 'yarramate/core@0.1#';
+const documentOf = (subject) => {
+    const hash = subject.indexOf('#');
+    return hash === -1 ? '' : subject.slice(0, hash);
+};
+const bySubjectOrder = (left, right) => documentOf(left).localeCompare(documentOf(right)) ||
+    left.localeCompare(right);
+const citation = (claim) => ({
+    path: claim.source.path,
+    line: claim.source.line,
+});
+export function buildGovernanceLog(workspace, graph, profileContext, options = {}) {
+    const conceptIds = new Set(graph.subjects.filter(({ type }) => type === 'concept').map(({ id }) => id));
+    const relationshipIds = new Set(graph.subjects
+        .filter(({ type }) => type === 'relationship')
+        .map(({ id }) => id));
+    const values = new Map();
+    const refs = new Map();
+    const attestations = new Map();
+    const definingClaims = [];
+    for (const claim of graph.claims) {
+        if (relationshipIds.has(claim.id) && 'ref' in claim.object) {
+            definingClaims.push(claim);
+            continue;
+        }
+        if ('ref' in claim.object) {
+            const key = `${claim.subject} ${claim.predicate}`;
+            refs.set(key, [...(refs.get(key) ?? []), claim.object.ref]);
+            continue;
+        }
+        if (claim.predicate.startsWith(ATTESTATION_PREDICATE_PREFIX)) {
+            attestations.set(claim.subject, [
+                ...(attestations.get(claim.subject) ?? []),
+                claim,
+            ]);
+            continue;
+        }
+        values.set(`${claim.subject} ${claim.predicate}`, claim.object.value);
+    }
+    const value = (subject, predicate) => values.get(`${subject} ${predicate}`);
+    const refsOf = (subject, predicate) => refs.get(`${subject} ${predicate}`) ?? [];
+    const kindOf = (subject) => value(subject, 'yarramate/concept/kind') ?? '';
+    const nameOf = (subject) => value(subject, 'yarramate/concept/name') ?? subject;
+    const refOf = (id) => ({ id, name: nameOf(id) });
+    const typeOf = (subject) => {
+        const kind = kindOf(subject);
+        return governanceTypeOf(profileContext.conceptKindLineages.get(kind), kind);
+    };
+    const coreKindOf = (relationshipKind) => (profileContext.relationshipKindLineages.get(relationshipKind) ?? [
+        relationshipKind,
+    ])[0];
+    const rowIds = (options.rows ?? [...conceptIds])
+        .filter((id) => conceptIds.has(id) && typeOf(id) !== null)
+        .sort(bySubjectOrder);
+    const rowSet = new Set(rowIds);
+    const outgoing = new Map();
+    const incoming = new Map();
+    for (const claim of definingClaims) {
+        if (!('ref' in claim.object))
+            continue;
+        const core = coreKindOf(claim.predicate);
+        if (rowSet.has(claim.subject)) {
+            outgoing.set(claim.subject, [
+                ...(outgoing.get(claim.subject) ?? []),
+                { core, to: claim.object.ref },
+            ]);
+        }
+        if (rowSet.has(claim.object.ref)) {
+            incoming.set(claim.object.ref, [
+                ...(incoming.get(claim.object.ref) ?? []),
+                { core, from: claim.subject },
+            ]);
+        }
+    }
+    const targets = (subject, core) => (outgoing.get(subject) ?? [])
+        .filter((edge) => edge.core === `${CORE}${core}`)
+        .map(({ to }) => to)
+        .sort(bySubjectOrder)
+        .map(refOf);
+    const sources = (subject, cores) => (incoming.get(subject) ?? [])
+        .filter((edge) => cores.some((core) => edge.core === `${CORE}${core}`))
+        .map(({ from }) => from)
+        .sort(bySubjectOrder)
+        .map(refOf);
+    const latestReview = (subject, topic) => {
+        let latest = null;
+        for (const claim of attestations.get(subject) ?? []) {
+            if (claim.predicate !== `${ATTESTATION_PREDICATE_PREFIX}${topic}`)
+                continue;
+            if (!('value' in claim.object))
+                continue;
+            const parts = parseAttestationClaimValue(claim.object.value);
+            if (parts === undefined)
+                continue;
+            if (latest === null || parts.on >= latest.on) {
+                latest = { topic, on: parts.on, by: parts.by, source: citation(claim) };
+            }
+        }
+        return latest;
+    };
+    const rows = rowIds.map((subject) => {
+        const type = typeOf(subject);
+        const owner = refsOf(subject, 'yarramate/ownership/owner')[0];
+        const description = value(subject, 'yarramate/concept/description');
+        return {
+            subject,
+            name: nameOf(subject),
+            kind: kindOf(subject),
+            type,
+            status: value(subject, 'yarramate/lifecycle/status') ?? null,
+            ...(description === undefined ? {} : { description }),
+            owner: owner === undefined ? null : refOf(owner),
+            threatens: type === 'risk' ? targets(subject, 'influence') : [],
+            bearsOn: type === 'assumption' ? targets(subject, 'association') : [],
+            mitigatedBy: type === 'risk' ? sources(subject, ['influence', 'association']) : [],
+            review: latestReview(subject, REVIEW_TOPICS[type]),
+            supersedes: [...refsOf(subject, 'yarramate/lineage/supersedes')].sort(),
+            groupedBy: sources(subject, ['aggregation']),
+        };
+    });
+    const ids = (predicate) => rows.filter(predicate).map(({ subject }) => subject);
+    const unowned = ids((row) => row.owner === null);
+    const unmitigated = ids((row) => row.type === 'risk' && row.status === 'current' && row.mitigatedBy.length === 0);
+    const unconfirmed = ids((row) => row.type === 'assumption' && row.review === null);
+    const unreviewed = ids((row) => row.type === 'risk' && row.review === null);
+    return {
+        format: 'yarramate/governance/v1',
+        workspace,
+        summary: {
+            rows: rows.length,
+            risks: rows.filter(({ type }) => type === 'risk').length,
+            assumptions: rows.filter(({ type }) => type === 'assumption').length,
+            unowned: unowned.length,
+            unmitigated: unmitigated.length,
+            unconfirmed: unconfirmed.length,
+            unreviewed: unreviewed.length,
+        },
+        rows,
+        gaps: { unowned, unmitigated, unconfirmed, unreviewed },
+    };
+}
+const escapeCell = (text) => text.replaceAll('|', '\\|');
+const names = (entries) => entries.map(({ name }) => escapeCell(name)).join(', ');
+const list = (ids) => ids.length === 0 ? 'none' : ids.map((id) => `\`${id}\``).join(', ');
+/** The log as one markdown table a person reads, with the gaps under it. */
+export function renderGovernanceMarkdown(log) {
+    const lines = ['# Governance log', ''];
+    lines.push(`Workspace \`${log.workspace}\`: ${log.summary.risks} risk${log.summary.risks === 1 ? '' : 's'}, ${log.summary.assumptions} assumption${log.summary.assumptions === 1 ? '' : 's'}. Derived from the record; edit the native documents, not this file.`, '');
+    if (log.rows.length === 0) {
+        lines.push('_No rows._', '');
+    }
+    else {
+        lines.push('| Subject | Type | Status | Owner | Threatens / bears on | Mitigated by | Review | Grouped by |', '|---|---|---|---|---|---|---|---|');
+        for (const row of log.rows) {
+            const review = row.review === null ? '' : `${row.review.topic} ${row.review.on} by ${escapeCell(row.review.by)}`;
+            lines.push(`| ${escapeCell(row.name)} (\`${row.subject}\`) | ${row.type} | ${row.status ?? ''} | ${row.owner === null ? '' : escapeCell(row.owner.name)} | ${names(row.type === 'risk' ? row.threatens : row.bearsOn)} | ${names(row.mitigatedBy)} | ${review} | ${names(row.groupedBy)} |`);
+        }
+        lines.push('');
+    }
+    lines.push('## Gaps', '', `- Unowned: ${list(log.gaps.unowned)}`, `- Unmitigated (current risks): ${list(log.gaps.unmitigated)}`, `- Unconfirmed assumptions: ${list(log.gaps.unconfirmed)}`, `- Unreviewed risks: ${list(log.gaps.unreviewed)}`, '');
+    return `${lines.join('\n')}\n`;
+}

package/dist/graph-projection.d.ts

@@ -78,6 +78,12 @@ export interface CanvasEdge {
      * kind. The canvas draws these only when the view asks (`showResponsibility`).
      */
     readonly responsibility?: ResponsibilityLetter | null;
+    /**
+     * A reading the endpoints decide (ADR 0160): "threatens" for an
+     * influence from a risk, "mitigates" for one into a risk, "bears on" for
+     * an association from an assumption. Absent, the kind's own reading.
+     */
+    readonly reading?: string;
     readonly from: string;
     readonly to: string;
     readonly name: string | null;