yarramate 0.13.0 → 0.14.0

package/README.md

@@ -5,6 +5,8 @@
 [![CodeQL](https://github.com/yarrasys/yarramate/actions/workflows/codeql.yml/badge.svg)](https://github.com/yarrasys/yarramate/actions/workflows/codeql.yml)
 [![license: MIT](https://img.shields.io/github/license/yarrasys/yarramate)](LICENSE)
 
+Product site: **[yarramate.dev](https://yarramate.dev)**
+
 YarraMate keeps your coding agents' architecture context correct. Declare
 the design once, as a checked model in git; agents receive prose rendered
 from it — bounded briefs and open design questions — and the CLI

package/dist/adapter-mapping.js

@@ -1,7 +1,6 @@
 import Ajv2020Module from 'ajv/dist/2020.js';
 import { diagnosticOrder, loadSourceDocument, locateSourcePath, } from './source-document.js';
-import adapterMappingSchema from '../schema/yarramate-adapter-mapping.schema.json' with {
-    type: 'json'
+import adapterMappingSchema from '../schema/yarramate-adapter-mapping.schema.json' with { type: 'json'
 };
 const Ajv2020 = Ajv2020Module.default;
 const validateSchema = new Ajv2020({ allErrors: true }).compile(adapterMappingSchema);

package/dist/adapters/likec4-cli.js

@@ -12,11 +12,9 @@ import { adapterMappingLocation, loadAdapterMapping, validateAdapterMapping, } f
 import { locateSourcePath } from '../source-document.js';
 import { prepareLikeC4Export, } from './likec4-prepare.js';
 import { exportLikeC4Project, loadLikeC4ProjectDefinition, } from './likec4-project.js';
-import generatedProjectSchema from '../../schema/yarramate-likec4-generated-project.schema.json' with {
-    type: 'json'
+import generatedProjectSchema from '../../schema/yarramate-likec4-generated-project.schema.json' with { type: 'json'
 };
-import generatedProjectV2Schema from '../../schema/yarramate-likec4-generated-project-v2.schema.json' with {
-    type: 'json'
+import generatedProjectV2Schema from '../../schema/yarramate-likec4-generated-project-v2.schema.json' with { type: 'json'
 };
 const Ajv2020 = Ajv2020Module.default;
 const validateGeneratedProjectMarker = new Ajv2020({

package/dist/adapters/likec4-kind-mapping.js

@@ -1,7 +1,6 @@
 import Ajv2020Module from 'ajv/dist/2020.js';
 import { diagnosticOrder, loadSourceDocument, locateSourcePath, } from '../source-document.js';
-import kindMappingSchema from '../../schema/yarramate-likec4-kind-mapping.schema.json' with {
-    type: 'json'
+import kindMappingSchema from '../../schema/yarramate-likec4-kind-mapping.schema.json' with { type: 'json'
 };
 const Ajv2020 = Ajv2020Module.default;
 const validateSchema = new Ajv2020({ allErrors: true }).compile(kindMappingSchema);

package/dist/adapters/likec4-project.js

@@ -1,8 +1,7 @@
 import Ajv2020Module from 'ajv/dist/2020.js';
 import { loadSourceDocument } from '../source-document.js';
 import { exportLikeC4, } from './likec4-export.js';
-import likeC4ProjectSchema from '../../schema/yarramate-likec4-project.schema.json' with {
-    type: 'json'
+import likeC4ProjectSchema from '../../schema/yarramate-likec4-project.schema.json' with { type: 'json'
 };
 const Ajv2020 = Ajv2020Module.default;
 const validateLikeC4Project = new Ajv2020({ allErrors: true }).compile(likeC4ProjectSchema);

package/dist/apply-command.js

@@ -6,8 +6,7 @@ import { diagnosticJson, humanDiagnostics, usage, } from './cli-support.js';
 import { compileWorkspace } from './compiler.js';
 import { loadSourceDocument, locateSourcePath, } from './source-document.js';
 import { loadWorkspaceManifest } from './workspace.js';
-import operationsSchema from '../schema/yarramate-operations.schema.json' with {
-    type: 'json'
+import operationsSchema from '../schema/yarramate-operations.schema.json' with { type: 'json'
 };
 const Ajv2020 = Ajv2020Module.default;
 const validateOperations = new Ajv2020({ allErrors: true }).compile(operationsSchema);
@@ -114,12 +113,15 @@ const itemMap = (source, collection, id) => {
     const pair = pairFor(root, collection);
     if (pair === undefined || !isSeq(pair.value))
         return undefined;
-    const found = pair.value.items.find((candidate) => isMap(candidate) &&
+    const sequence = pair.value;
+    const found = sequence.items.find((candidate) => isMap(candidate) &&
         candidate.items.some((field) => isScalar(field.key) &&
             field.key.value === 'id' &&
             isScalar(field.value) &&
             field.value.value === id));
-    return found === undefined ? undefined : { map: found };
+    return found === undefined
+        ? undefined
+        : { map: found, sequence };
 };
 // The indent item fields sit at, read off the item's own first field.
 const fieldIndentOf = (source, map) => indentAt(source, nodeRange(map.items[0].key)[0]);
@@ -208,6 +210,40 @@ const removeField = (source, map, key) => {
         : nodeRange(pair.value)[2];
     return splice(source, start, lineEndAfter(source, valueEnd), '');
 };
+// Whole-subject deletion (#123): remove the exact authored item range,
+// marker line included. Unlike field removal — where line deletion on a
+// flow item would silently take the whole item (the 0.8.1 regression) —
+// deleting the whole item is precisely the intent here, so flow-style
+// items in a block sequence share the line-based path. An item inside a
+// flow collection rewrites the collection value instead, and removing
+// the last item leaves an explicit empty collection: the document
+// schema requires the key.
+const removeCollectionItem = (source, collection, id) => {
+    const { map, sequence } = itemMap(source, collection, id);
+    if (sequence.flow) {
+        const remaining = sequence.toJSON().filter((item) => item.id !== id);
+        const [start, valueEnd] = nodeRange(sequence);
+        return splice(source, start, valueEnd, remaining.length === 0
+            ? '[]'
+            : stringify(remaining, {
+                collectionStyle: 'flow',
+                lineWidth: 0,
+            }).trimEnd());
+    }
+    // Node ranges may extend past the trailing newline to the next line
+    // start; afterContentLine anchors the removal on the item's own last
+    // content line.
+    const end = afterContentLine(source, nodeRange(map)[2]);
+    if (sequence.items.length === 1) {
+        let valueStart = nodeRange(sequence)[0];
+        while (valueStart > 0 &&
+            (source[valueStart - 1] === ' ' || source[valueStart - 1] === '\n')) {
+            valueStart -= 1;
+        }
+        return splice(source, valueStart, end, ' []\n');
+    }
+    return splice(source, lineStartOf(source, nodeRange(map)[0]), end, '');
+};
 // ---------------------------------------------------------------------------
 export function runApplyCommand(options, cwd) {
     const json = options.includes('--json');
@@ -253,16 +289,20 @@ export function runApplyCommand(options, cwd) {
             addedRelationships: 0,
             updatedConcepts: 0,
             updatedRelationships: 0,
+            deletedConcepts: 0,
+            deletedRelationships: 0,
         };
+        const deletions = [];
+        const locateOperation = (index, message) => ({
+            severity: 'error',
+            code: 'YM912',
+            message,
+            ...locateSourcePath(operationsPath, yaml, lineCounter, ['operations', index, 'document'], `/operations/${index}/document`),
+        });
         for (const [index, operation] of operations.entries()) {
             const absolute = resolve(cwd, operation.document);
             const manifestPath = workspaceDocuments.get(absolute);
-            const locate = (message) => ({
-                severity: 'error',
-                code: 'YM912',
-                message,
-                ...locateSourcePath(operationsPath, yaml, lineCounter, ['operations', index, 'document'], `/operations/${index}/document`),
-            });
+            const locate = (message) => locateOperation(index, message);
             if (manifestPath === undefined) {
                 return failed([
                     locate(`Operation ${index} targets "${operation.document}", which is not a document of workspace "${workspace.id}"`),
@@ -280,6 +320,26 @@ export function runApplyCommand(options, cwd) {
                 source = appendCollectionItem(source, 'relationships', operation.relationship);
                 counts.addedRelationships += 1;
             }
+            else if (operation.op === 'delete-concept' ||
+                operation.op === 'delete-relationship') {
+                const collection = operation.op === 'delete-concept' ? 'concepts' : 'relationships';
+                const id = operation.op === 'delete-concept'
+                    ? operation.concept.id
+                    : operation.relationship.id;
+                if (itemMap(source, collection, id) === undefined) {
+                    return failed([
+                        locate(`Operation ${index} deletes "${id}", which does not exist in ${operation.document}`),
+                    ]);
+                }
+                source = removeCollectionItem(source, collection, id);
+                deletions.push({ index, absolute, id });
+                if (operation.op === 'delete-concept') {
+                    counts.deletedConcepts += 1;
+                }
+                else {
+                    counts.deletedRelationships += 1;
+                }
+            }
             else {
                 const collection = operation.op === 'update-concept' ? 'concepts' : 'relationships';
                 const payload = (operation.op === 'update-concept'
@@ -334,6 +394,92 @@ export function runApplyCommand(options, cwd) {
             }
             candidates.set(absolute, source);
         }
+        // Reference integrity for deletes (#123), evaluated against the
+        // post-batch state: stage everything first, then look, so a concept
+        // deleted together with its referring relationships in one batch
+        // succeeds while a target anything still points at rejects the
+        // whole batch. Referring sites are relationship endpoints, owner,
+        // constraint and identified references; projection selectors are
+        // deliberately unchecked — they tolerate no-match by design. The
+        // compile gate below stays the backstop.
+        if (deletions.length > 0) {
+            const staged = workspace.documents.map((path) => {
+                const absolute = resolve(cwd, path);
+                return {
+                    absolute,
+                    value: parseDocument(candidates.get(absolute) ?? readFileSync(absolute, 'utf8')).toJSON(),
+                };
+            });
+            const qualify = (documentId, reference) => reference.includes('#') ? reference : `${documentId}#${reference}`;
+            const referrers = staged.flatMap(({ value }) => {
+                const documentId = value?.id;
+                if (documentId === undefined)
+                    return [];
+                const sites = [];
+                for (const concept of value?.concepts ?? []) {
+                    const subject = `${documentId}#${concept.id}`;
+                    if (concept.owner !== undefined) {
+                        sites.push({
+                            ref: qualify(documentId, concept.owner),
+                            subject,
+                            field: 'owner',
+                        });
+                    }
+                    for (const constraint of concept.constraints ?? []) {
+                        sites.push({
+                            ref: qualify(documentId, constraint.ref),
+                            subject,
+                            field: 'constraints',
+                        });
+                    }
+                    for (const reference of concept.references ?? []) {
+                        sites.push({
+                            ref: qualify(documentId, reference.ref),
+                            subject,
+                            field: 'references',
+                        });
+                    }
+                }
+                for (const relationship of value?.relationships ?? []) {
+                    const subject = `${documentId}#${relationship.id}`;
+                    for (const endpoint of ['from', 'to']) {
+                        const reference = relationship[endpoint];
+                        if (reference !== undefined) {
+                            sites.push({
+                                ref: qualify(documentId, reference),
+                                subject,
+                                field: endpoint,
+                            });
+                        }
+                    }
+                    for (const reference of relationship.references ?? []) {
+                        sites.push({
+                            ref: qualify(documentId, reference.ref),
+                            subject,
+                            field: 'references',
+                        });
+                    }
+                }
+                return sites;
+            });
+            const documentIds = new Map(staged.map(({ absolute, value }) => [absolute, value?.id]));
+            const violations = deletions.flatMap((deletion) => {
+                const documentId = documentIds.get(deletion.absolute);
+                if (documentId === undefined)
+                    return [];
+                const target = `${documentId}#${deletion.id}`;
+                const referring = referrers.filter((site) => site.ref === target);
+                if (referring.length === 0)
+                    return [];
+                return [
+                    locateOperation(deletion.index, `Operation ${deletion.index} deletes "${deletion.id}", which is still referenced by ${referring
+                        .map((site) => `"${site.subject}" (${site.field})`)
+                        .join(', ')}`),
+                ];
+            });
+            if (violations.length > 0)
+                return failed(violations);
+        }
         // The atomic gate: the whole candidate workspace must compile before a
         // single byte is written; any diagnostic rejects the entire batch.
         const compilation = compileWorkspace([...workspace.profiles, ...workspace.documents].map((path) => {
@@ -366,7 +512,9 @@ export function runApplyCommand(options, cwd) {
         const applied = counts.addedConcepts +
             counts.addedRelationships +
             counts.updatedConcepts +
-            counts.updatedRelationships;
+            counts.updatedRelationships +
+            counts.deletedConcepts +
+            counts.deletedRelationships;
         return {
             exitCode: 0,
             stdout: `Applied ${applied} operation${applied === 1 ? '' : 's'} to ${touched.join(', ')}\n`,

package/dist/ask-command.js

@@ -3,7 +3,7 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseDocument } from 'yaml';
 import { compareArchitectureStates, } from './architecture-state.js';
-import { renderBrief } from './brief.js';
+import { coreLocalKind, renderBrief } from './brief.js';
 import { deriveChangedSubjects } from './changed.js';
 import { runCheckCommand } from './check-command.js';
 import { diagnosticJson, humanDiagnostics, usage, } from './cli-support.js';
@@ -105,18 +105,118 @@ const plannedLines = (subjects) => {
         return `  ${subject.id.padEnd(width)}  ${clauses.join('; ')}`;
     });
 };
+// On a dense graph, hub seeds make 1-hop connected expansion reach most
+// of the model (a focused ask on a 248-concept model reached 243). The
+// cap keeps each seed's most material neighbours and announces the rest
+// (ADR 0070); --neighbours overrides it, 0 lifts it.
+const defaultNeighbourCap = 12;
+const motivationKindIds = new Set(conceptKinds
+    .filter(({ layer }) => layer === 'motivation')
+    .map(({ id }) => id));
+// Neighbours rank by the same reading the brief ranks paragraphs with
+// under a budget (ADR 0042/0055): motivation first, then planned,
+// current, retired. Ties break on seed affinity (a neighbour touching
+// more seeds is more material to the slice), then id — deterministic.
+const materialityRank = (graph, profileContext, id) => {
+    const kind = claimValue(graph.claims, id, 'yarramate/concept/kind');
+    const core = kind === undefined
+        ? undefined
+        : coreLocalKind(kind, profileContext?.conceptKindLineages);
+    if (core !== undefined && motivationKindIds.has(core))
+        return 0;
+    const status = claimValue(graph.claims, id, 'yarramate/lifecycle/status');
+    return status === 'planned' ? 1 : status === 'retired' ? 3 : 2;
+};
 // The one-hop connected neighbourhood every slice and advice mode uses:
 // the same machinery context --subject exposed, now seeded by matching.
-const sliceProjection = (graph, seeds, title, profileContext) => evaluateProjection(graph, {
-    format: 'yarramate/projection/v1',
-    id: 'ask-slice',
-    version: '0.0',
-    query: { subjects: [...seeds], relationships: 'connected' },
-    presentation: {
-        title,
-        description: `Connected neighbourhood of ${seeds.join(', ')}`,
-    },
-}, profileContext);
+// The capped result is always a subset of the uncapped one — the cap
+// drops neighbours and their edges, never seeds, and never adds edges
+// the connected expansion would not have selected.
+const sliceProjection = (graph, seeds, title, profileContext, neighbourCap) => {
+    const full = evaluateProjection(graph, {
+        format: 'yarramate/projection/v1',
+        id: 'ask-slice',
+        version: '0.0',
+        query: { subjects: [...seeds], relationships: 'connected' },
+        presentation: {
+            title,
+            description: `Connected neighbourhood of ${seeds.join(', ')}`,
+        },
+    }, profileContext);
+    if (neighbourCap === 0)
+        return { result: full };
+    const seedSet = new Set(seeds);
+    const relationshipIds = new Set(full.subjects
+        .filter(({ type }) => type === 'relationship')
+        .map(({ id }) => id));
+    const endpointsById = new Map();
+    for (const claim of full.claims) {
+        if (relationshipIds.has(claim.id) && 'ref' in claim.object) {
+            endpointsById.set(claim.id, [claim.subject, claim.object.ref]);
+        }
+    }
+    const neighboursOf = new Map(seeds.map((seed) => [seed, []]));
+    const affinity = new Map();
+    for (const [from, to] of endpointsById.values()) {
+        for (const [seed, neighbour] of [
+            [from, to],
+            [to, from],
+        ]) {
+            if (!seedSet.has(seed) || seedSet.has(neighbour))
+                continue;
+            const list = neighboursOf.get(seed);
+            if (list !== undefined && !list.includes(neighbour)) {
+                list.push(neighbour);
+                affinity.set(neighbour, (affinity.get(neighbour) ?? 0) + 1);
+            }
+        }
+    }
+    const keptNeighbours = new Set();
+    for (const list of neighboursOf.values()) {
+        const ordered = [...list].sort((left, right) => materialityRank(graph, profileContext, left) -
+            materialityRank(graph, profileContext, right) ||
+            (affinity.get(right) ?? 0) - (affinity.get(left) ?? 0) ||
+            left.localeCompare(right));
+        for (const neighbour of ordered.slice(0, neighbourCap)) {
+            keptNeighbours.add(neighbour);
+        }
+    }
+    const allNeighbours = new Set([...neighboursOf.values()].flat());
+    const omitted = allNeighbours.size - keptNeighbours.size;
+    if (omitted === 0)
+        return { result: full };
+    const keptConcepts = new Set([...seedSet, ...keptNeighbours]);
+    const keptRelationships = new Set([...endpointsById]
+        .filter(([, [from, to]]) => keptConcepts.has(from) && keptConcepts.has(to))
+        .map(([id]) => id));
+    const keptSubjects = new Set([...keptConcepts, ...keptRelationships]);
+    const keptDocuments = new Set([...keptConcepts].map((id) => id.slice(0, id.indexOf('#'))));
+    const result = {
+        ...full,
+        documents: full.documents.filter(({ id }) => keptDocuments.has(id)),
+        subjects: full.subjects.filter(({ id }) => keptSubjects.has(id)),
+        claims: full.claims.filter((claim) => (keptConcepts.has(claim.subject) && !relationshipIds.has(claim.id)) ||
+            keptRelationships.has(claim.subject) ||
+            keptRelationships.has(claim.id)),
+    };
+    return {
+        result,
+        neighbourhood: {
+            cap: neighbourCap,
+            kept: keptNeighbours.size,
+            omitted,
+            omittedBySeed: seeds.flatMap((seed) => {
+                const dropped = (neighboursOf.get(seed) ?? []).filter((neighbour) => !keptNeighbours.has(neighbour)).length;
+                return dropped > 0 ? [{ seed, omitted: dropped }] : [];
+            }),
+        },
+    };
+};
+// The honesty line, in the budgeted-ladder voice (ADR 0042): what was
+// dropped is named, and so is the way to widen.
+const neighbourhoodLine = (neighbourhood) => `[neighbours ${neighbourhood.cap}: ${neighbourhood.omitted} of ` +
+    `${neighbourhood.kept + neighbourhood.omitted} neighbours omitted — ` +
+    `raise --neighbours or pass --neighbours 0 for the full neighbourhood]`;
 export function runAskCommand(options, cwd) {
     let json = false;
     let subjects = false;
@@ -128,6 +228,7 @@ export function runAskCommand(options, cwd) {
     let compare;
     let changed;
     let budget;
+    let neighbours;
     let kindFilter;
     let statusFilter;
     let cataloguePath;
@@ -177,6 +278,7 @@ export function runAskCommand(options, cwd) {
             continue;
         }
         if (option === '--budget' ||
+            option === '--neighbours' ||
             option === '--kind' ||
             option === '--status' ||
             option === '--catalogue' ||
@@ -191,6 +293,12 @@ export function runAskCommand(options, cwd) {
                 }
                 budget = Number(value);
             }
+            else if (option === '--neighbours') {
+                if (neighbours !== undefined || !/^(0|[1-9][0-9]*)$/.test(value)) {
+                    return { exitCode: 2, stdout: '', stderr: usage };
+                }
+                neighbours = Number(value);
+            }
             else if (option === '--changed') {
                 if (changed !== undefined) {
                     return { exitCode: 2, stdout: '', stderr: usage };
@@ -241,6 +349,7 @@ export function runAskCommand(options, cwd) {
                 advise ||
                 changed !== undefined ||
                 budget !== undefined ||
+                neighbours !== undefined ||
                 query.length === 0)) ||
         (query.length > 0 && exclusiveModes > 0) ||
         (changed !== undefined &&
@@ -248,7 +357,11 @@ export function runAskCommand(options, cwd) {
         ((kindFilter !== undefined || statusFilter !== undefined) && !subjects) ||
         (cataloguePath !== undefined && !open && !advise) ||
         (budget !== undefined &&
-            (json || (query.length === 0 && !advise && changed === undefined)))) {
+            (json || (query.length === 0 && !advise && changed === undefined))) ||
+        (neighbours !== undefined &&
+            query.length === 0 &&
+            !advise &&
+            changed === undefined)) {
         return { exitCode: 2, stdout: '', stderr: usage };
     }
     try {
@@ -615,7 +728,7 @@ export function runAskCommand(options, cwd) {
                 projections: workspace.projections.length,
                 uncovered,
             };
-            const evaluated = sliceProjection(graph, seeds, `Review slice ${changed}`, compilation.profileContext);
+            const { result: evaluated, neighbourhood } = sliceProjection(graph, seeds, `Review slice ${changed}`, compilation.profileContext, neighbours ?? defaultNeighbourCap);
             const result = {
                 format: 'yarramate/ask-result/v1',
                 workspace: workspace.id,
@@ -624,6 +737,7 @@ export function runAskCommand(options, cwd) {
                 seeds,
                 changed: derived.changed,
                 coverage,
+                ...(neighbourhood === undefined ? {} : { neighbourhood }),
                 result: evaluated,
             };
             if (changedIds.length === 0) {
@@ -637,6 +751,9 @@ export function runAskCommand(options, cwd) {
                     `${plural(derived.changed.relationships.length, 'relationship')} changed (workspace ${workspace.id})`,
                 '',
                 rendered.trimEnd(),
+                ...(neighbourhood === undefined
+                    ? []
+                    : ['', neighbourhoodLine(neighbourhood)]),
                 '',
                 uncovered.length === 0
                     ? `Review coverage: every changed subject appears in at least one of the ${coverage.projections} authored projections.`
@@ -657,6 +774,17 @@ export function runAskCommand(options, cwd) {
             : undefined;
         if (projectionCandidate !== undefined &&
             parseDocument(readFileSync(projectionCandidate, 'utf8')).get('format') === 'yarramate/projection/v1') {
+            // A projection file defines its own query; there is no seeded
+            // expansion to cap, so an explicit --neighbours is a contradiction
+            // rather than something to ignore silently.
+            if (neighbours !== undefined) {
+                return {
+                    exitCode: 2,
+                    stdout: '',
+                    stderr: `--neighbours applies to seeded slices; ${soleTerm} is a ` +
+                        'projection that defines its own query\n',
+                };
+            }
             const loaded = loadProjection({
                 path: soleTerm,
                 source: readFileSync(projectionCandidate, 'utf8'),
@@ -772,7 +900,7 @@ export function runAskCommand(options, cwd) {
             lines.push('', note);
             return emit(result, `${lines.join('\n')}\n`);
         }
-        const evaluated = sliceProjection(graph, resolution.seeds, topic, compilation.profileContext);
+        const { result: evaluated, neighbourhood } = sliceProjection(graph, resolution.seeds, topic, compilation.profileContext, neighbours ?? defaultNeighbourCap);
         if (!advise) {
             const result = {
                 format: 'yarramate/ask-result/v1',
@@ -782,6 +910,7 @@ export function runAskCommand(options, cwd) {
                 topic,
                 seeds: resolution.seeds,
                 matched: resolution.matched,
+                ...(neighbourhood === undefined ? {} : { neighbourhood }),
                 result: evaluated,
             };
             const rendered = budget === undefined
@@ -794,7 +923,9 @@ export function runAskCommand(options, cwd) {
                         : '') +
                     `: ${resolution.seeds.join(', ')}\n\n`
                 : '';
-            return emit(result, `${header}${rendered}`);
+            return emit(result, neighbourhood === undefined
+                ? `${header}${rendered}`
+                : `${header}${rendered.trimEnd()}\n\n${neighbourhoodLine(neighbourhood)}\n`);
         }
         // --advise: the expert composition. The engine assembles ground
         // truth — slice, open questions, drift — and stops; the reading and
@@ -874,6 +1005,7 @@ export function runAskCommand(options, cwd) {
             seeds: resolution.seeds,
             matched: resolution.matched,
             slice: brief,
+            ...(neighbourhood === undefined ? {} : { neighbourhood }),
             openQuestions,
             ...(reconciliation === undefined ? {} : { reconciliation }),
         };
@@ -884,6 +1016,9 @@ export function runAskCommand(options, cwd) {
             '== Model slice ==',
             '',
             brief.trimEnd(),
+            ...(neighbourhood === undefined
+                ? []
+                : ['', neighbourhoodLine(neighbourhood)]),
             '',
             '== Open questions touching this slice ==',
         ];

package/dist/brief.d.ts

@@ -1,3 +1,4 @@
 import type { ResolvedProfileContext } from './compiler.js';
 import type { ProjectionResult } from './projection.js';
+export declare const coreLocalKind: (kind: string, lineages: ReadonlyMap<string, readonly string[]> | undefined) => string | undefined;
 export declare function renderBrief(result: ProjectionResult, profileContext?: ResolvedProfileContext, budgetTokens?: number): string;

package/dist/brief.js

@@ -14,7 +14,9 @@ const claimReferences = (claims, subject, predicate) => claims.flatMap((claim) =
     : []);
 // Resolve a qualified kind to its nearest core-profile local id through
 // declared lineage, mirroring how `next` orients relationships (ADR 0048).
-const coreLocalKind = (kind, lineages) => {
+// Exported so ask's neighbour cap ranks neighbours by the same reading
+// the brief ranks paragraphs with (ADR 0070).
+export const coreLocalKind = (kind, lineages) => {
     for (const candidate of [kind, ...(lineages?.get(kind) ?? [])]) {
         const separator = candidate.indexOf('#');
         if (separator !== -1 && candidate.startsWith('yarramate/core@')) {

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> --where \"<free text>\" | <document-id>#<local-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>] [--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> [--changed <git-range>]\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>] [--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>\" | <document-id>#<local-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>\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> [--changed <git-range>]\n";
 export declare const diagnosticJson: (diagnostics: unknown) => string;
 export declare const checkResultJson: (ok: boolean, diagnostics: unknown, counted?: {
     readonly documents: number;
@@ -18,7 +18,7 @@ export declare const checkResultJson: (ok: boolean, diagnostics: unknown, counte
     readonly observations: number;
     readonly contradicted: number;
 }) => string;
-export declare const humanDiagnostics: (diagnostics: readonly Pick<Diagnostic, "path" | "line" | "column" | "code" | "message">[]) => string;
+export declare const humanDiagnostics: (diagnostics: readonly Pick<Diagnostic, 'path' | 'line' | 'column' | 'code' | 'message'>[]) => string;
 export declare const sortDiagnostics: <T extends Diagnostic>(diagnostics: readonly T[]) => T[];
 export declare const resolveCliWorkspaceSources: (paths: readonly string[], cwd: string, options?: {
     readonly includeAdapterMappings?: boolean;

package/dist/cli-support.js

@@ -3,8 +3,7 @@ import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseDocument } from 'yaml';
 import { loadWorkspaceManifest } from './workspace.js';
-import packageManifest from '../package.json' with {
-    type: 'json'
+import packageManifest from '../package.json' with { type: 'json'
 };
 export const isMainModule = (moduleUrl, entrypoint) => {
     if (entrypoint === undefined)
@@ -23,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 <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> --where "<free text>" | <document-id>#<local-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>] [--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> [--changed <git-range>]\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>] [--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>" | <document-id>#<local-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>\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> [--changed <git-range>]\n';
 export const diagnosticJson = (diagnostics) => `${JSON.stringify({
     format: 'yarramate/diagnostic-result/v1',
     diagnostics,

package/dist/compiler.js

@@ -2,11 +2,9 @@ import Ajv2020Module from 'ajv/dist/2020.js';
 import { LineCounter, parseDocument } from 'yaml';
 import { conceptKinds, relationshipPolicies, } from './profile.js';
 import { closestCandidate, describeSchemaViolation, } from './source-document.js';
-import documentSchema from '../schema/yarramate-document.schema.json' with {
-    type: 'json'
+import documentSchema from '../schema/yarramate-document.schema.json' with { type: 'json'
 };
-import profileSchema from '../schema/yarramate-profile.schema.json' with {
-    type: 'json'
+import profileSchema from '../schema/yarramate-profile.schema.json' with { type: 'json'
 };
 const coreProfile = 'yarramate/core@0.1';
 const Ajv2020 = Ajv2020Module.default;

package/dist/core-contract.js

@@ -1,8 +1,7 @@
 import Ajv2020Module from 'ajv/dist/2020.js';
 import { LineCounter, parseDocument } from 'yaml';
 import { diagnosticOrder, loadSourceDocument, locateSourcePath, } from './source-document.js';
-import coreContractSchema from '../schema/yarramate-core-contract.schema.json' with {
-    type: 'json'
+import coreContractSchema from '../schema/yarramate-core-contract.schema.json' with { type: 'json'
 };
 const Ajv2020 = Ajv2020Module.default;
 const validateCoreContract = new Ajv2020({ allErrors: true }).compile(coreContractSchema);

package/dist/evidence.js

@@ -1,7 +1,6 @@
 import Ajv2020Module from 'ajv/dist/2020.js';
 import { diagnosticOrder, loadSourceDocument, locateSourcePath, } from './source-document.js';
-import evidenceSchema from '../schema/yarramate-evidence.schema.json' with {
-    type: 'json'
+import evidenceSchema from '../schema/yarramate-evidence.schema.json' with { type: 'json'
 };
 const Ajv2020 = Ajv2020Module.default;
 const validateEvidenceSchema = new Ajv2020({ allErrors: true }).compile(evidenceSchema);

package/dist/interrogate-command.js

@@ -1,7 +1,6 @@
 import Ajv2020Module from 'ajv/dist/2020.js';
 import { loadSourceDocument, locateSourcePath, } from './source-document.js';
-import catalogueSchema from '../schema/yarramate-question-catalogue.schema.json' with {
-    type: 'json'
+import catalogueSchema from '../schema/yarramate-question-catalogue.schema.json' with { type: 'json'
 };
 const Ajv2020 = Ajv2020Module.default;
 const validateCatalogue = new Ajv2020({ allErrors: true }).compile(catalogueSchema);

package/dist/profile.d.ts

@@ -1,5 +1,5 @@
-export declare const layers: readonly ["motivation", "strategy", "business", "application", "technology", "physical", "implementation", "composite"];
-export declare const aspects: readonly ["motivation", "active-structure", "behavior", "passive-structure", "composite"];
+export declare const layers: readonly ['motivation', 'strategy', 'business', 'application', 'technology', 'physical', 'implementation', 'composite'];
+export declare const aspects: readonly ['motivation', 'active-structure', 'behavior', 'passive-structure', 'composite'];
 export type Layer = (typeof layers)[number];
 export type Aspect = (typeof aspects)[number];
 export interface ConceptKind {
@@ -14,7 +14,7 @@ export interface ConceptKind {
     readonly inspiredBy: string;
 }
 export declare const conceptKinds: readonly ConceptKind[];
-export declare const relationshipKinds: readonly ["composition", "aggregation", "assignment", "realization", "serving", "access", "influence", "association", "triggering", "flow", "specialization"];
+export declare const relationshipKinds: readonly ['composition', 'aggregation', 'assignment', 'realization', 'serving', 'access', 'influence', 'association', 'triggering', 'flow', 'specialization'];
 export type RelationshipKind = (typeof relationshipKinds)[number];
 export interface RelationshipPolicy {
     readonly id: RelationshipKind;

package/dist/projection.js

@@ -1,7 +1,6 @@
 import Ajv2020Module from 'ajv/dist/2020.js';
 import { loadSourceDocument } from './source-document.js';
-import projectionSchema from '../schema/yarramate-projection.schema.json' with {
-    type: 'json'
+import projectionSchema from '../schema/yarramate-projection.schema.json' with { type: 'json'
 };
 const Ajv2020 = Ajv2020Module.default;
 const validateProjection = new Ajv2020({ allErrors: true }).compile(projectionSchema);

package/dist/source-document.d.ts

@@ -20,7 +20,7 @@ export type SourceDocumentResult<T> = {
     readonly diagnostics: readonly Diagnostic[];
 };
 export declare const diagnosticOrder: (left: Diagnostic, right: Diagnostic) => number;
-export declare const describeSchemaViolation: (error: Pick<ErrorObject, "keyword" | "message" | "params">) => string;
+export declare const describeSchemaViolation: (error: Pick<ErrorObject, 'keyword' | 'message' | 'params'>) => string;
 export declare const closestCandidate: (value: string, candidates: Iterable<string>) => string | undefined;
 export declare function locateSourcePath(sourcePath: string, yaml: ReturnType<typeof parseDocument>, lineCounter: LineCounter, yamlPath: readonly (string | number)[], pointer: string): SourceLocation;
 export declare function loadSourceDocument<T>(source: WorkspaceSource, validate: ValidateFunction, schemaLabel: string): SourceDocumentResult<T>;

package/dist/workspace.js

@@ -2,8 +2,7 @@ import { globSync, realpathSync, statSync } from 'node:fs';
 import { dirname, isAbsolute, relative, resolve, sep, } from 'node:path';
 import Ajv2020Module from 'ajv/dist/2020.js';
 import { diagnosticOrder, loadSourceDocument, } from './source-document.js';
-import workspaceSchema from '../schema/yarramate-workspace.schema.json' with {
-    type: 'json'
+import workspaceSchema from '../schema/yarramate-workspace.schema.json' with { type: 'json'
 };
 const Ajv2020 = Ajv2020Module.default;
 const validateWorkspace = new Ajv2020({ allErrors: true }).compile(workspaceSchema);

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "yarramate",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Tool-neutral semantic architecture engine and guided methodology",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/yarrasys/yarramate.git"
   },
-  "homepage": "https://github.com/yarrasys/yarramate#readme",
+  "homepage": "https://yarramate.dev",
   "bugs": {
     "url": "https://github.com/yarrasys/yarramate/issues"
   },
@@ -108,9 +108,9 @@
     "yaml": "^2.8.1"
   },
   "devDependencies": {
-    "@types/node": "^24.0.0",
+    "@types/node": "^26.1.2",
     "likec4": "^1.59.2",
-    "typescript": "^5.9.0",
+    "typescript": "^7.0.2",
     "vitest": "^4.1.10"
   }
 }

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

@@ -15,13 +15,17 @@
         "addedConcepts",
         "addedRelationships",
         "updatedConcepts",
-        "updatedRelationships"
+        "updatedRelationships",
+        "deletedConcepts",
+        "deletedRelationships"
       ],
       "properties": {
         "addedConcepts": { "type": "integer", "minimum": 0 },
         "addedRelationships": { "type": "integer", "minimum": 0 },
         "updatedConcepts": { "type": "integer", "minimum": 0 },
-        "updatedRelationships": { "type": "integer", "minimum": 0 }
+        "updatedRelationships": { "type": "integer", "minimum": 0 },
+        "deletedConcepts": { "type": "integer", "minimum": 0 },
+        "deletedRelationships": { "type": "integer", "minimum": 0 }
       }
     },
     "documents": {

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

@@ -263,6 +263,9 @@
             }
           },
           "additionalProperties": false
+        },
+        "neighbourhood": {
+          "$ref": "#/$defs/neighbourhoodOmission"
         }
       },
       "additionalProperties": false
@@ -302,6 +305,9 @@
           "type": "string",
           "minLength": 1
         },
+        "neighbourhood": {
+          "$ref": "#/$defs/neighbourhoodOmission"
+        },
         "openQuestions": {
           "type": "array",
           "items": {
@@ -707,6 +713,52 @@
     }
   ],
   "$defs": {
+    "neighbourhoodOmission": {
+      "description": "Present only when the per-seed neighbour cap dropped part of the 1-hop expansion (ADR 0070): the cap in force, neighbours kept and omitted in total, and the per-seed omission counts. Absent means the slice is the complete connected neighbourhood.",
+      "type": "object",
+      "required": [
+        "cap",
+        "kept",
+        "omitted",
+        "omittedBySeed"
+      ],
+      "properties": {
+        "cap": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "kept": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "omitted": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "omittedBySeed": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "seed",
+              "omitted"
+            ],
+            "properties": {
+              "seed": {
+                "type": "string",
+                "minLength": 1
+              },
+              "omitted": {
+                "type": "integer",
+                "minimum": 1
+              }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
     "conceptEntry": {
       "type": "object",
       "required": [

package/schema/yarramate-operations.schema.json

@@ -170,6 +170,18 @@
         }
       }
     },
+    "deleteTarget": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/nonEmptyText"
+        }
+      }
+    },
     "operation": {
       "oneOf": [
         {
@@ -327,6 +339,46 @@
               }
             }
           }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "op",
+            "document",
+            "concept"
+          ],
+          "properties": {
+            "op": {
+              "const": "delete-concept"
+            },
+            "document": {
+              "$ref": "#/$defs/nonEmptyText"
+            },
+            "concept": {
+              "$ref": "#/$defs/deleteTarget"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "op",
+            "document",
+            "relationship"
+          ],
+          "properties": {
+            "op": {
+              "const": "delete-relationship"
+            },
+            "document": {
+              "$ref": "#/$defs/nonEmptyText"
+            },
+            "relationship": {
+              "$ref": "#/$defs/deleteTarget"
+            }
+          }
         }
       ]
     }

package/skills/yarramate-architecture/references/native-authoring.md

@@ -168,8 +168,12 @@ yarramate apply operations.yaml workspace.yaml
 ```
 
 The whole candidate workspace must compile or nothing is written.
-Update operations enrich only — scalars replace, lists append; removals
-stay Git edits.
+Update operations enrich by default — scalars replace, lists append — and
+retract explicitly with `remove: [<field> ...]`. Whole subjects leave
+through `delete-concept` / `delete-relationship` (payload: the `id` only),
+rejected while anything still references the target; delete the referring
+relationships in the same batch. To descope, retire (`status: retired`)
+instead — delete only when the history itself is noise.
 
 ## Ownership and constraints