yarramate 0.8.1 → 0.10.0

package/dist/ask-command.js

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { parseDocument } from 'yaml';
 import { compareArchitectureStates, } from './architecture-state.js';
 import { renderBrief } from './brief.js';
+import { deriveChangedSubjects } from './changed.js';
 import { runCheckCommand } from './check-command.js';
 import { diagnosticJson, humanDiagnostics, usage, } from './cli-support.js';
 import { compileWorkspaceWithProfileContext, } from './compiler.js';
@@ -124,6 +125,7 @@ export function runAskCommand(options, cwd) {
     let kinds = false;
     let advise = false;
     let compare;
+    let changed;
     let budget;
     let kindFilter;
     let statusFilter;
@@ -172,7 +174,8 @@ export function runAskCommand(options, cwd) {
         if (option === '--budget' ||
             option === '--kind' ||
             option === '--status' ||
-            option === '--catalogue') {
+            option === '--catalogue' ||
+            option === '--changed') {
             const value = options[index + 1];
             if (value === undefined || value.startsWith('-')) {
                 return { exitCode: 2, stdout: '', stderr: usage };
@@ -183,6 +186,12 @@ export function runAskCommand(options, cwd) {
                 }
                 budget = Number(value);
             }
+            else if (option === '--changed') {
+                if (changed !== undefined) {
+                    return { exitCode: 2, stdout: '', stderr: usage };
+                }
+                changed = value;
+            }
             else if (option === '--kind') {
                 if (kindFilter !== undefined) {
                     return { exitCode: 2, stdout: '', stderr: usage };
@@ -223,9 +232,12 @@ export function runAskCommand(options, cwd) {
         (advise && exclusiveModes > 0) ||
         (advise && query.length === 0) ||
         (query.length > 0 && exclusiveModes > 0) ||
+        (changed !== undefined &&
+            (query.length > 0 || exclusiveModes > 0 || advise)) ||
         ((kindFilter !== undefined || statusFilter !== undefined) && !subjects) ||
         (cataloguePath !== undefined && !open && !advise) ||
-        (budget !== undefined && (json || (query.length === 0 && !advise)))) {
+        (budget !== undefined &&
+            (json || (query.length === 0 && !advise && changed === undefined)))) {
         return { exitCode: 2, stdout: '', stderr: usage };
     }
     try {
@@ -263,7 +275,8 @@ export function runAskCommand(options, cwd) {
             !open &&
             !kinds &&
             !advise &&
-            compare === undefined) {
+            compare === undefined &&
+            changed === undefined) {
             const checked = runCheckCommand([workspacePath, '--json'], cwd);
             const checkPayload = JSON.parse(checked.stdout);
             if (!checkPayload.ok) {
@@ -544,6 +557,83 @@ export function runAskCommand(options, cwd) {
             };
             return emit(result, renderInterrogationReport(ordered));
         }
+        // --changed: the review slice (ADR 0065). Git says what changed; the
+        // engine maps changed lines to subjects and renders their connected
+        // neighbourhood, plus a coverage note when a changed subject appears
+        // in no authored projection.
+        if (changed !== undefined) {
+            const documentIdByPath = new Map(graph.documents.map(({ id, source }) => [source, id]));
+            const derived = deriveChangedSubjects(cwd, changed, workspace.documents.map((path) => ({
+                path,
+                source: readFileSync(resolve(cwd, path), 'utf8'),
+                documentId: documentIdByPath.get(path) ?? path,
+            })));
+            if (!derived.ok) {
+                return { exitCode: 2, stdout: '', stderr: `${derived.message}\n` };
+            }
+            const endpoints = new Set();
+            for (const relationshipId of derived.changed.relationships) {
+                const claim = graph.claims.find((candidate) => candidate.id === relationshipId && 'ref' in candidate.object);
+                if (claim !== undefined && 'ref' in claim.object) {
+                    endpoints.add(claim.subject);
+                    endpoints.add(claim.object.ref);
+                }
+            }
+            const seeds = [
+                ...new Set([...derived.changed.concepts, ...endpoints]),
+            ].sort();
+            const changedIds = [
+                ...derived.changed.concepts,
+                ...derived.changed.relationships,
+            ];
+            const covered = new Set();
+            for (const projectionPath of workspace.projections) {
+                const loaded = loadProjection({
+                    path: projectionPath,
+                    source: readFileSync(resolve(cwd, projectionPath), 'utf8'),
+                });
+                if (!loaded.ok)
+                    continue;
+                const membership = evaluateProjection(graph, loaded.projection, compilation.profileContext);
+                for (const subject of membership.subjects) {
+                    covered.add(subject.id);
+                }
+            }
+            const uncovered = changedIds.filter((id) => !covered.has(id));
+            const coverage = {
+                projections: workspace.projections.length,
+                uncovered,
+            };
+            const evaluated = sliceProjection(graph, seeds, `Review slice ${changed}`, compilation.profileContext);
+            const result = {
+                format: 'yarramate/ask-result/v1',
+                workspace: workspace.id,
+                mode: 'slice',
+                addressing: 'changed',
+                seeds,
+                changed: derived.changed,
+                coverage,
+                result: evaluated,
+            };
+            if (changedIds.length === 0) {
+                return emit(result, `No model subjects changed in ${changed}.\n`);
+            }
+            const rendered = budget === undefined
+                ? renderBrief(evaluated, compilation.profileContext)
+                : renderBudgetedContext(evaluated, budget);
+            const lines = [
+                `Review slice ${changed} — ${plural(derived.changed.concepts.length, 'concept')}, ` +
+                    `${plural(derived.changed.relationships.length, 'relationship')} changed (workspace ${workspace.id})`,
+                '',
+                rendered.trimEnd(),
+                '',
+                uncovered.length === 0
+                    ? `Review coverage: every changed subject appears in at least one of the ${coverage.projections} authored projections.`
+                    : `Review coverage: ${uncovered.length} of ${changedIds.length} changed subjects appear in no authored projection:` +
+                        `\n${uncovered.map((id) => `  ${id}`).join('\n')}`,
+            ];
+            return emit(result, `${lines.join('\n')}\n`);
+        }
         // Slice and advice both start from seeds. A single query term that
         // names a projection file is precise addressing; anything else runs
         // through free-text seeding, where exact subject ids win.

package/dist/changed.d.ts

@@ -0,0 +1,17 @@
+export interface ChangedSubjects {
+    readonly range: string;
+    readonly concepts: readonly string[];
+    readonly relationships: readonly string[];
+}
+export type ChangedResult = {
+    readonly ok: true;
+    readonly changed: ChangedSubjects;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+export declare function deriveChangedSubjects(cwd: string, range: string, documents: ReadonlyArray<{
+    readonly path: string;
+    readonly source: string;
+    readonly documentId: string;
+}>): ChangedResult;

package/dist/changed.js

@@ -0,0 +1,111 @@
+import { spawnSync } from 'node:child_process';
+import { isMap, isScalar, isSeq, parseDocument } from 'yaml';
+const lineOfOffset = (lineStarts, offset) => {
+    let low = 0;
+    let high = lineStarts.length - 1;
+    while (low < high) {
+        const mid = (low + high + 1) >> 1;
+        if (lineStarts[mid] <= offset)
+            low = mid;
+        else
+            high = mid - 1;
+    }
+    return low + 1;
+};
+const itemSpans = (source) => {
+    const lineStarts = [0];
+    for (let index = 0; index < source.length; index += 1) {
+        if (source[index] === '\n')
+            lineStarts.push(index + 1);
+    }
+    const document = parseDocument(source);
+    const root = document.contents;
+    if (!isMap(root))
+        return [];
+    const spans = [];
+    for (const collection of ['concepts', 'relationships', 'states']) {
+        const pair = root.items.find((candidate) => isScalar(candidate.key) && candidate.key.value === collection);
+        if (pair === undefined || !isSeq(pair.value))
+            continue;
+        for (const item of pair.value.items) {
+            if (!isMap(item))
+                continue;
+            const idPair = item.items.find((field) => isScalar(field.key) && field.key.value === 'id');
+            if (idPair === undefined ||
+                !isScalar(idPair.value) ||
+                typeof idPair.value.value !== 'string') {
+                continue;
+            }
+            const range = item
+                .range;
+            if (range === undefined)
+                continue;
+            spans.push({
+                id: idPair.value.value,
+                collection,
+                startLine: lineOfOffset(lineStarts, range[0]),
+                // range[1] can extend past the trailing newline; anchor the end
+                // on the last content character instead.
+                endLine: lineOfOffset(lineStarts, Math.max(range[0], range[1] - 1)),
+            });
+        }
+    }
+    return spans;
+};
+// New-side line ranges from `git diff --unified=0`. A pure deletion has a
+// zero count; it still touches the position it collapsed onto.
+const changedLineRanges = (diff) => {
+    const ranges = [];
+    for (const match of diff.matchAll(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/gm)) {
+        const start = Number(match[1]);
+        const count = match[2] === undefined ? 1 : Number(match[2]);
+        ranges.push(count === 0 ? [Math.max(start, 1), Math.max(start, 1)] : [start, start + count - 1]);
+    }
+    return ranges;
+};
+export function deriveChangedSubjects(cwd, range, documents) {
+    const probe = spawnSync('git', ['-C', cwd, 'rev-parse', '--git-dir'], {
+        encoding: 'utf8',
+    });
+    if (probe.status !== 0) {
+        return {
+            ok: false,
+            message: '--changed requires the workspace to live in a git repository',
+        };
+    }
+    const concepts = new Set();
+    const relationships = new Set();
+    for (const document of documents) {
+        const diffed = spawnSync('git', ['-C', cwd, 'diff', '--unified=0', range, '--', document.path], { encoding: 'utf8' });
+        if (diffed.status !== 0) {
+            return {
+                ok: false,
+                message: `git diff failed for range "${range}": ${(diffed.stderr ?? '').trim()}`,
+            };
+        }
+        const ranges = changedLineRanges(diffed.stdout ?? '');
+        if (ranges.length === 0)
+            continue;
+        const spans = itemSpans(document.source);
+        for (const span of spans) {
+            if (span.collection === 'states')
+                continue;
+            const touched = ranges.some(([from, to]) => from <= span.endLine && to >= span.startLine);
+            if (!touched)
+                continue;
+            const qualified = `${document.documentId}#${span.id}`;
+            if (span.collection === 'concepts')
+                concepts.add(qualified);
+            else
+                relationships.add(qualified);
+        }
+    }
+    return {
+        ok: true,
+        changed: {
+            range,
+            concepts: [...concepts].sort(),
+            relationships: [...relationships].sort(),
+        },
+    };
+}

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 <document-id>#<local-id>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> \"<free text>\" | <document-id>#<local-id> ... | <projection.yaml> [--budget <tokens>] [--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>] [--catalogue <catalogue.yaml>] [--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 check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml>\n  yarramate export graph <workspace.yaml> [--out <file>]\n  yarramate export markdown <projection.yaml> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml>\n";
+export declare const usage = "Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate design <workspace.yaml> [--subject <document-id>#<local-id>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> \"<free text>\" | <document-id>#<local-id> ... | <projection.yaml> [--budget <tokens>] [--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>] [--catalogue <catalogue.yaml>] [--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>] [--json]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml>\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 likec4 <likec4-project.yaml> <output-dir> <workspace.yaml>\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

@@ -23,7 +23,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 <document-id>#<local-id>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> "<free text>" | <document-id>#<local-id> ... | <projection.yaml> [--budget <tokens>] [--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>] [--catalogue <catalogue.yaml>] [--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 check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml>\n  yarramate export graph <workspace.yaml> [--out <file>]\n  yarramate export markdown <projection.yaml> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml>\n';
+export const usage = 'Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate design <workspace.yaml> [--subject <document-id>#<local-id>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> "<free text>" | <document-id>#<local-id> ... | <projection.yaml> [--budget <tokens>] [--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>] [--catalogue <catalogue.yaml>] [--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>] [--json]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml>\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 likec4 <likec4-project.yaml> <output-dir> <workspace.yaml>\n';
 export const diagnosticJson = (diagnostics) => `${JSON.stringify({
     format: 'yarramate/diagnostic-result/v1',
     diagnostics,

package/dist/export-command.js

@@ -4,6 +4,7 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseDocument } from 'yaml';
 import { renderBrief } from './brief.js';
+import { deriveChangedSubjects } from './changed.js';
 import { humanDiagnostics, usage } from './cli-support.js';
 import { compileWorkspaceWithProfileContext, } from './compiler.js';
 import { serializeSemanticGraph } from './graph.js';
@@ -23,6 +24,7 @@ const parseExportOptions = (options) => {
     const positionals = [];
     let out;
     let budget;
+    let changed;
     let json = false;
     for (let index = 0; index < options.length; index += 1) {
         const option = options[index];
@@ -30,7 +32,9 @@ const parseExportOptions = (options) => {
             json = true;
             continue;
         }
-        if (option === '--out' || option === '--budget') {
+        if (option === '--out' ||
+            option === '--budget' ||
+            option === '--changed') {
             const value = options[index + 1];
             if (value === undefined || value.startsWith('-'))
                 return undefined;
@@ -39,6 +43,11 @@ const parseExportOptions = (options) => {
                     return undefined;
                 out = value;
             }
+            else if (option === '--changed') {
+                if (changed !== undefined)
+                    return undefined;
+                changed = value;
+            }
             else {
                 if (budget !== undefined || !/^[1-9][0-9]*$/.test(value)) {
                     return undefined;
@@ -56,6 +65,7 @@ const parseExportOptions = (options) => {
         positionals,
         ...(out === undefined ? {} : { out }),
         ...(budget === undefined ? {} : { budget }),
+        ...(changed === undefined ? {} : { changed }),
         json,
     };
 };
@@ -103,12 +113,14 @@ export function runExportCommand(options, cwd) {
             stderr: delegated.stderr ?? '',
         };
     }
-    const expectedPositionals = kind === 'graph' ? 1 : 2;
+    const usesChanged = parsed.changed !== undefined;
+    const expectedPositionals = kind === 'graph' || usesChanged ? 1 : 2;
     const workspacePath = parsed.positionals[expectedPositionals - 1];
-    const projectionPath = kind === 'graph' ? undefined : parsed.positionals[0];
+    const projectionPath = kind === 'graph' || usesChanged ? undefined : parsed.positionals[0];
     if (parsed.positionals.length !== expectedPositionals ||
         workspacePath === undefined ||
         parsed.json ||
+        (usesChanged && kind === 'graph') ||
         (parsed.budget !== undefined && kind !== 'briefs') ||
         (kind === 'briefs' && parsed.out === undefined)) {
         return { exitCode: 2, stdout: '', stderr: usage };
@@ -151,13 +163,51 @@ export function runExportCommand(options, cwd) {
                 stderr: '',
             };
         }
-        const loadedProjection = loadProjection({
-            path: projectionPath,
-            source: readFileSync(resolve(cwd, projectionPath), 'utf8'),
-        });
-        if (!loadedProjection.ok)
-            return failed(loadedProjection.diagnostics);
-        const result = evaluateProjection(compilation.graph, loadedProjection.projection, compilation.profileContext);
+        let result;
+        if (parsed.changed !== undefined) {
+            // Review slices derive from git (ADR 0065): changed subjects seed
+            // the connected neighbourhood the reviewer inspects.
+            const documentIdByPath = new Map(compilation.graph.documents.map(({ id, source }) => [source, id]));
+            const derived = deriveChangedSubjects(cwd, parsed.changed, workspace.documents.map((path) => ({
+                path,
+                source: readFileSync(resolve(cwd, path), 'utf8'),
+                documentId: documentIdByPath.get(path) ?? path,
+            })));
+            if (!derived.ok) {
+                return { exitCode: 2, stdout: '', stderr: `${derived.message}\n` };
+            }
+            const endpoints = new Set();
+            for (const relationshipId of derived.changed.relationships) {
+                const claim = compilation.graph.claims.find((candidate) => candidate.id === relationshipId && 'ref' in candidate.object);
+                if (claim !== undefined && 'ref' in claim.object) {
+                    endpoints.add(claim.subject);
+                    endpoints.add(claim.object.ref);
+                }
+            }
+            const seeds = [
+                ...new Set([...derived.changed.concepts, ...endpoints]),
+            ].sort();
+            result = evaluateProjection(compilation.graph, {
+                format: 'yarramate/projection/v1',
+                id: 'review-slice',
+                version: '0.0',
+                query: { subjects: seeds, relationships: 'connected' },
+                presentation: {
+                    title: `Review slice ${parsed.changed}`,
+                    description: `Connected neighbourhood of the subjects changed in ` +
+                        `${parsed.changed}.`,
+                },
+            }, compilation.profileContext);
+        }
+        else {
+            const loadedProjection = loadProjection({
+                path: projectionPath,
+                source: readFileSync(resolve(cwd, projectionPath), 'utf8'),
+            });
+            if (!loadedProjection.ok)
+                return failed(loadedProjection.diagnostics);
+            result = evaluateProjection(compilation.graph, loadedProjection.projection, compilation.profileContext);
+        }
         if (kind === 'markdown') {
             const rendered = renderProjectionMarkdown(result);
             if (parsed.out === undefined) {

package/dist/projection.d.ts

@@ -9,6 +9,7 @@ export interface ProjectionDefinition {
         readonly documents?: readonly string[];
         readonly kinds?: readonly string[];
         readonly statuses?: readonly LifecycleStatus[];
+        readonly excludeStatuses?: readonly LifecycleStatus[];
         readonly states?: readonly string[];
         readonly owners?: readonly string[];
         readonly constraints?: readonly string[];

package/dist/projection.js

@@ -65,6 +65,9 @@ export function evaluateProjection(graph, projection, profileContext) {
             (projection.query.statuses === undefined ||
                 (status !== undefined &&
                     projection.query.statuses.includes(status))) &&
+            (projection.query.excludeStatuses === undefined ||
+                status === undefined ||
+                !projection.query.excludeStatuses.includes(status)) &&
             (projection.query.owners === undefined ||
                 (owner !== undefined &&
                     projection.query.owners.includes(owner))) &&
@@ -80,8 +83,12 @@ export function evaluateProjection(graph, projection, profileContext) {
             if (subject.type !== 'relationship')
                 continue;
             const relationship = graph.claims.find((claim) => claim.id === subject.id);
+            const relationshipStatus = claimValue(graph.claims, subject.id, 'yarramate/lifecycle/status');
             if (relationship === undefined ||
                 !('ref' in relationship.object) ||
+                (projection.query.excludeStatuses !== undefined &&
+                    relationshipStatus !== undefined &&
+                    projection.query.excludeStatuses.includes(relationshipStatus)) ||
                 (projection.query.relationshipKinds !== undefined &&
                     !projection.query.relationshipKinds.some((selectedKind) => selectedKind === relationship.predicate ||
                         (projection.query.kindMatching === 'descendants' &&
@@ -93,6 +100,20 @@ export function evaluateProjection(graph, projection, profileContext) {
             }
             const sourceSelected = initiallySelectedConceptIds.has(relationship.subject);
             const targetSelected = initiallySelectedConceptIds.has(relationship.object.ref);
+            // excludeStatuses also vetoes connected expansion: an excluded
+            // concept is never pulled in as a neighbour, and edges touching
+            // one are dropped rather than left dangling.
+            const endpointExcluded = (id) => {
+                if (projection.query.excludeStatuses === undefined)
+                    return false;
+                const endpointStatus = claimValue(graph.claims, id, 'yarramate/lifecycle/status');
+                return (endpointStatus !== undefined &&
+                    projection.query.excludeStatuses.includes(endpointStatus));
+            };
+            if (endpointExcluded(relationship.subject) ||
+                endpointExcluded(relationship.object.ref)) {
+                continue;
+            }
             if ((relationshipMode === 'between' &&
                 sourceSelected &&
                 targetSelected) ||

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yarramate",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "description": "Tool-neutral semantic architecture engine and guided methodology",
   "license": "MIT",
   "repository": {

package/schema/yarramate-ask-result.schema.json

@@ -4,7 +4,11 @@
   "title": "YarraMate ask result",
   "description": "One envelope for every consumed-now read: orientation, roster, slice, advice, next, open questions, and state comparison, discriminated by mode.",
   "type": "object",
-  "required": ["format", "workspace", "mode"],
+  "required": [
+    "format",
+    "workspace",
+    "mode"
+  ],
   "properties": {
     "format": {
       "const": "yarramate/ask-result/v1"
@@ -29,18 +33,34 @@
   "oneOf": [
     {
       "type": "object",
-      "required": ["mode", "ok", "check", "backlog"],
+      "required": [
+        "mode",
+        "ok",
+        "check",
+        "backlog"
+      ],
       "properties": {
         "format": true,
         "workspace": true,
-        "mode": { "const": "orientation" },
-        "ok": { "type": "boolean" },
+        "mode": {
+          "const": "orientation"
+        },
+        "ok": {
+          "type": "boolean"
+        },
         "check": {
           "type": "object",
-          "required": ["ok", "diagnostics"],
+          "required": [
+            "ok",
+            "diagnostics"
+          ],
           "properties": {
-            "ok": { "type": "boolean" },
-            "diagnostics": { "type": "array" },
+            "ok": {
+              "type": "boolean"
+            },
+            "diagnostics": {
+              "type": "array"
+            },
             "counted": {
               "type": "object",
               "required": [
@@ -50,10 +70,18 @@
                 "states"
               ],
               "properties": {
-                "documents": { "type": "integer" },
-                "concepts": { "type": "integer" },
-                "relationships": { "type": "integer" },
-                "states": { "type": "integer" }
+                "documents": {
+                  "type": "integer"
+                },
+                "concepts": {
+                  "type": "integer"
+                },
+                "relationships": {
+                  "type": "integer"
+                },
+                "states": {
+                  "type": "integer"
+                }
               },
               "additionalProperties": false
             }
@@ -65,28 +93,47 @@
         },
         "design": {
           "type": "object",
-          "required": ["catalogue", "open"],
+          "required": [
+            "catalogue",
+            "open"
+          ],
           "properties": {
-            "catalogue": { "type": "string", "minLength": 1 },
-            "open": { "type": "integer", "minimum": 0 }
+            "catalogue": {
+              "type": "string",
+              "minLength": 1
+            },
+            "open": {
+              "type": "integer",
+              "minimum": 0
+            }
           },
           "additionalProperties": false
         },
         "backlog": {
           "type": "object",
-          "required": ["planned", "current", "retired"],
+          "required": [
+            "planned",
+            "current",
+            "retired"
+          ],
           "properties": {
             "planned": {
               "type": "array",
-              "items": { "$ref": "#/$defs/nextSubject" }
+              "items": {
+                "$ref": "#/$defs/nextSubject"
+              }
             },
             "current": {
               "type": "array",
-              "items": { "$ref": "#/$defs/conceptEntry" }
+              "items": {
+                "$ref": "#/$defs/conceptEntry"
+              }
             },
             "retired": {
               "type": "array",
-              "items": { "$ref": "#/$defs/conceptEntry" }
+              "items": {
+                "$ref": "#/$defs/conceptEntry"
+              }
             }
           },
           "additionalProperties": false
@@ -96,36 +143,119 @@
     },
     {
       "type": "object",
-      "required": ["mode", "total", "subjects"],
+      "required": [
+        "mode",
+        "total",
+        "subjects"
+      ],
       "properties": {
         "format": true,
         "workspace": true,
-        "mode": { "const": "roster" },
-        "total": { "type": "integer", "minimum": 0 },
+        "mode": {
+          "const": "roster"
+        },
+        "total": {
+          "type": "integer",
+          "minimum": 0
+        },
         "subjects": {
           "type": "array",
-          "items": { "$ref": "#/$defs/conceptEntry" }
+          "items": {
+            "$ref": "#/$defs/conceptEntry"
+          }
         }
       },
       "additionalProperties": false
     },
     {
       "type": "object",
-      "required": ["mode", "addressing", "result"],
+      "required": [
+        "mode",
+        "addressing",
+        "result"
+      ],
       "properties": {
         "format": true,
         "workspace": true,
-        "mode": { "const": "slice" },
+        "mode": {
+          "const": "slice"
+        },
         "addressing": {
-          "enum": ["free-text", "subjects", "projection"]
+          "enum": [
+            "free-text",
+            "subjects",
+            "projection",
+            "changed"
+          ]
+        },
+        "topic": {
+          "type": "string",
+          "minLength": 1
         },
-        "topic": { "type": "string", "minLength": 1 },
         "seeds": {
           "type": "array",
-          "items": { "type": "string", "minLength": 1 }
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "matched": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "result": {
+          "$ref": "#/$defs/projectionResult"
         },
-        "matched": { "type": "integer", "minimum": 0 },
-        "result": { "$ref": "#/$defs/projectionResult" }
+        "changed": {
+          "type": "object",
+          "required": [
+            "range",
+            "concepts",
+            "relationships"
+          ],
+          "properties": {
+            "range": {
+              "type": "string",
+              "minLength": 1
+            },
+            "concepts": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "relationships": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          },
+          "additionalProperties": false
+        },
+        "coverage": {
+          "type": "object",
+          "required": [
+            "projections",
+            "uncovered"
+          ],
+          "properties": {
+            "projections": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "uncovered": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          },
+          "additionalProperties": false
+        }
       },
       "additionalProperties": false
     },
@@ -142,36 +272,84 @@
       "properties": {
         "format": true,
         "workspace": true,
-        "mode": { "const": "advice" },
-        "topic": { "type": "string", "minLength": 1 },
+        "mode": {
+          "const": "advice"
+        },
+        "topic": {
+          "type": "string",
+          "minLength": 1
+        },
         "seeds": {
           "type": "array",
-          "items": { "type": "string", "minLength": 1 }
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "matched": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "slice": {
+          "type": "string",
+          "minLength": 1
         },
-        "matched": { "type": "integer", "minimum": 0 },
-        "slice": { "type": "string", "minLength": 1 },
         "openQuestions": {
           "type": "array",
           "items": {
             "type": "object",
-            "required": ["wave", "id", "authority", "question", "materiality"],
+            "required": [
+              "wave",
+              "id",
+              "authority",
+              "question",
+              "materiality"
+            ],
             "properties": {
-              "wave": { "type": "string", "minLength": 1 },
-              "id": { "type": "string", "minLength": 1 },
-              "authority": { "enum": ["human", "agent", "either"] },
-              "question": { "type": "string", "minLength": 1 },
-              "materiality": { "type": "string", "minLength": 1 },
-              "subject": { "type": "string", "minLength": 1 }
+              "wave": {
+                "type": "string",
+                "minLength": 1
+              },
+              "id": {
+                "type": "string",
+                "minLength": 1
+              },
+              "authority": {
+                "enum": [
+                  "human",
+                  "agent",
+                  "either"
+                ]
+              },
+              "question": {
+                "type": "string",
+                "minLength": 1
+              },
+              "materiality": {
+                "type": "string",
+                "minLength": 1
+              },
+              "subject": {
+                "type": "string",
+                "minLength": 1
+              }
             },
             "additionalProperties": false
           }
         },
         "reconciliation": {
           "type": "object",
-          "required": ["summary", "findings"],
+          "required": [
+            "summary",
+            "findings"
+          ],
           "properties": {
-            "summary": { "$ref": "#/$defs/reconciliationSummary" },
-            "findings": { "type": "array" }
+            "summary": {
+              "$ref": "#/$defs/reconciliationSummary"
+            },
+            "findings": {
+              "type": "array"
+            }
           },
           "additionalProperties": false
         }
@@ -180,34 +358,62 @@
     },
     {
       "type": "object",
-      "required": ["mode", "subjects"],
+      "required": [
+        "mode",
+        "subjects"
+      ],
       "properties": {
         "format": true,
         "workspace": true,
-        "mode": { "const": "next" },
+        "mode": {
+          "const": "next"
+        },
         "subjects": {
           "type": "array",
-          "items": { "$ref": "#/$defs/nextSubject" }
+          "items": {
+            "$ref": "#/$defs/nextSubject"
+          }
         }
       },
       "additionalProperties": false
     },
     {
       "type": "object",
-      "required": ["mode", "report"],
+      "required": [
+        "mode",
+        "report"
+      ],
       "properties": {
         "format": true,
         "workspace": true,
-        "mode": { "const": "open" },
+        "mode": {
+          "const": "open"
+        },
         "report": {
           "type": "object",
-          "required": ["format", "workspace", "catalogue", "summary", "waves"],
+          "required": [
+            "format",
+            "workspace",
+            "catalogue",
+            "summary",
+            "waves"
+          ],
           "properties": {
-            "format": { "const": "yarramate/interrogation-report/v1" },
-            "workspace": { "type": "string" },
-            "catalogue": { "type": "string" },
-            "summary": { "type": "object" },
-            "waves": { "type": "array" }
+            "format": {
+              "const": "yarramate/interrogation-report/v1"
+            },
+            "workspace": {
+              "type": "string"
+            },
+            "catalogue": {
+              "type": "string"
+            },
+            "summary": {
+              "type": "object"
+            },
+            "waves": {
+              "type": "array"
+            }
           },
           "additionalProperties": false
         }
@@ -216,22 +422,48 @@
     },
     {
       "type": "object",
-      "required": ["mode", "conceptKinds", "relationshipKinds", "extensions"],
+      "required": [
+        "mode",
+        "conceptKinds",
+        "relationshipKinds",
+        "extensions"
+      ],
       "properties": {
         "format": true,
         "workspace": true,
-        "mode": { "const": "kinds" },
+        "mode": {
+          "const": "kinds"
+        },
         "conceptKinds": {
           "type": "array",
           "items": {
             "type": "object",
-            "required": ["id", "name", "layer", "aspect"],
+            "required": [
+              "id",
+              "name",
+              "layer",
+              "aspect"
+            ],
             "properties": {
-              "id": { "type": "string", "minLength": 1 },
-              "name": { "type": "string", "minLength": 1 },
-              "layer": { "type": "string", "minLength": 1 },
-              "aspect": { "type": "string", "minLength": 1 },
-              "inspiredBy": { "type": "string" }
+              "id": {
+                "type": "string",
+                "minLength": 1
+              },
+              "name": {
+                "type": "string",
+                "minLength": 1
+              },
+              "layer": {
+                "type": "string",
+                "minLength": 1
+              },
+              "aspect": {
+                "type": "string",
+                "minLength": 1
+              },
+              "inspiredBy": {
+                "type": "string"
+              }
             },
             "additionalProperties": false
           }
@@ -240,19 +472,34 @@
           "type": "array",
           "items": {
             "type": "object",
-            "required": ["id", "intent"],
+            "required": [
+              "id",
+              "intent"
+            ],
             "properties": {
-              "id": { "type": "string", "minLength": 1 },
-              "intent": { "type": "string", "minLength": 1 },
+              "id": {
+                "type": "string",
+                "minLength": 1
+              },
+              "intent": {
+                "type": "string",
+                "minLength": 1
+              },
               "sourceAspects": {
                 "type": "array",
-                "items": { "type": "string" }
+                "items": {
+                  "type": "string"
+                }
               },
               "targetAspects": {
                 "type": "array",
-                "items": { "type": "string" }
+                "items": {
+                  "type": "string"
+                }
               },
-              "repair": { "type": "string" }
+              "repair": {
+                "type": "string"
+              }
             },
             "additionalProperties": false
           }
@@ -261,13 +508,27 @@
           "type": "array",
           "items": {
             "type": "object",
-            "required": ["id", "type", "lineage"],
+            "required": [
+              "id",
+              "type",
+              "lineage"
+            ],
             "properties": {
-              "id": { "type": "string", "minLength": 1 },
-              "type": { "enum": ["concept", "relationship"] },
+              "id": {
+                "type": "string",
+                "minLength": 1
+              },
+              "type": {
+                "enum": [
+                  "concept",
+                  "relationship"
+                ]
+              },
               "lineage": {
                 "type": "array",
-                "items": { "type": "string" }
+                "items": {
+                  "type": "string"
+                }
               }
             },
             "additionalProperties": false
@@ -278,21 +539,45 @@
     },
     {
       "type": "object",
-      "required": ["mode", "comparison"],
+      "required": [
+        "mode",
+        "comparison"
+      ],
       "properties": {
         "format": true,
         "workspace": true,
-        "mode": { "const": "compare" },
+        "mode": {
+          "const": "compare"
+        },
         "comparison": {
           "type": "object",
-          "required": ["format", "from", "to", "added", "removed", "retained"],
+          "required": [
+            "format",
+            "from",
+            "to",
+            "added",
+            "removed",
+            "retained"
+          ],
           "properties": {
-            "format": { "const": "yarramate/state-comparison/v1" },
-            "from": { "type": "string" },
-            "to": { "type": "string" },
-            "added": { "type": "array" },
-            "removed": { "type": "array" },
-            "retained": { "type": "array" }
+            "format": {
+              "const": "yarramate/state-comparison/v1"
+            },
+            "from": {
+              "type": "string"
+            },
+            "to": {
+              "type": "string"
+            },
+            "added": {
+              "type": "array"
+            },
+            "removed": {
+              "type": "array"
+            },
+            "retained": {
+              "type": "array"
+            }
           },
           "additionalProperties": false
         }
@@ -303,30 +588,67 @@
   "$defs": {
     "conceptEntry": {
       "type": "object",
-      "required": ["id", "kind"],
+      "required": [
+        "id",
+        "kind"
+      ],
       "properties": {
-        "id": { "type": "string", "minLength": 1 },
-        "kind": { "type": "string", "minLength": 1 },
-        "name": { "type": "string" },
-        "status": { "enum": ["planned", "current", "retired"] },
-        "description": { "type": "string" }
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "kind": {
+          "type": "string",
+          "minLength": 1
+        },
+        "name": {
+          "type": "string"
+        },
+        "status": {
+          "enum": [
+            "planned",
+            "current",
+            "retired"
+          ]
+        },
+        "description": {
+          "type": "string"
+        }
       },
       "additionalProperties": false
     },
     "nextSubject": {
       "type": "object",
-      "required": ["id", "kind", "dependsOn", "requiredBy", "evidence"],
+      "required": [
+        "id",
+        "kind",
+        "dependsOn",
+        "requiredBy",
+        "evidence"
+      ],
       "properties": {
-        "id": { "type": "string", "minLength": 1 },
-        "kind": { "type": "string", "minLength": 1 },
-        "name": { "type": "string" },
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "kind": {
+          "type": "string",
+          "minLength": 1
+        },
+        "name": {
+          "type": "string"
+        },
         "dependsOn": {
           "type": "array",
-          "items": { "type": "string" }
+          "items": {
+            "type": "string"
+          }
         },
         "requiredBy": {
           "type": "array",
-          "items": { "type": "string" }
+          "items": {
+            "type": "string"
+          }
         },
         "evidence": {
           "type": "object",
@@ -338,28 +660,58 @@
             "notObserved"
           ],
           "properties": {
-            "observations": { "type": "integer" },
-            "confirmed": { "type": "integer" },
-            "contradicted": { "type": "integer" },
-            "unknown": { "type": "integer" },
-            "notObserved": { "type": "integer" }
+            "observations": {
+              "type": "integer"
+            },
+            "confirmed": {
+              "type": "integer"
+            },
+            "contradicted": {
+              "type": "integer"
+            },
+            "unknown": {
+              "type": "integer"
+            },
+            "notObserved": {
+              "type": "integer"
+            }
           },
           "additionalProperties": false
         },
-        "cycle": { "const": true }
+        "cycle": {
+          "const": true
+        }
       },
       "additionalProperties": false
     },
     "projectionResult": {
       "type": "object",
-      "required": ["format", "projection", "documents", "subjects", "claims"],
+      "required": [
+        "format",
+        "projection",
+        "documents",
+        "subjects",
+        "claims"
+      ],
       "properties": {
-        "format": { "const": "yarramate/projection-result/v1" },
-        "projection": { "type": "string" },
-        "presentation": { "type": "object" },
-        "documents": { "type": "array" },
-        "subjects": { "type": "array" },
-        "claims": { "type": "array" }
+        "format": {
+          "const": "yarramate/projection-result/v1"
+        },
+        "projection": {
+          "type": "string"
+        },
+        "presentation": {
+          "type": "object"
+        },
+        "documents": {
+          "type": "array"
+        },
+        "subjects": {
+          "type": "array"
+        },
+        "claims": {
+          "type": "array"
+        }
       },
       "additionalProperties": false
     },
@@ -376,14 +728,30 @@
         "subjectsWithoutEvidence"
       ],
       "properties": {
-        "evidenceDocuments": { "type": "integer" },
-        "observations": { "type": "integer" },
-        "confirmed": { "type": "integer" },
-        "findings": { "type": "integer" },
-        "contradicted": { "type": "integer" },
-        "unknown": { "type": "integer" },
-        "notObserved": { "type": "integer" },
-        "subjectsWithoutEvidence": { "type": "integer" }
+        "evidenceDocuments": {
+          "type": "integer"
+        },
+        "observations": {
+          "type": "integer"
+        },
+        "confirmed": {
+          "type": "integer"
+        },
+        "findings": {
+          "type": "integer"
+        },
+        "contradicted": {
+          "type": "integer"
+        },
+        "unknown": {
+          "type": "integer"
+        },
+        "notObserved": {
+          "type": "integer"
+        },
+        "subjectsWithoutEvidence": {
+          "type": "integer"
+        }
       },
       "additionalProperties": false
     }

package/schema/yarramate-projection.schema.json

@@ -49,6 +49,14 @@
             "enum": ["planned", "current", "retired"]
           }
         },
+        "excludeStatuses": {
+          "description": "Drop concepts carrying one of these lifecycle statuses while keeping concepts that declare no status at all - 'everything except retired' for viewpoint projections, where a bare statuses filter would wrongly drop unstatused actors and motivation elements.",
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "enum": ["planned", "current", "retired"]
+          }
+        },
         "states": {
           "type": "array",
           "minItems": 1,