yarramate 0.12.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
@@ -17,6 +19,20 @@ whose gaps are found deterministically.
 > YarraMate is pre-release software. Interfaces may evolve before the first
 > stable release.
 
+## Proven across harnesses
+
+The design bet is that the model — not the session — is the state, so any
+agent in any harness can resume the work cold. We tested that adversarially
+on a real product: a Claude Code session worked the design interview all
+day, then an OpenAI Codex session — no shared context, the tool never
+named — resumed it from a ten-line pointer file and the published CLI. It
+answered 63 open design questions, filed two genuine defect reports, and in
+a later session reported that the model "was not merely documentation" — it
+caught an approval-path regression before the release shipped.
+
+The full story, with every commit, PR, and release attached:
+[The model is the handover](docs/CASE-STUDY-CROSS-HARNESS.md).
+
 ## Why YarraMate?
 
 Architecture documents often drift away from implementation or become tied to
@@ -134,6 +150,7 @@ node dist/cli.js ask .yarramate/workspace.yaml
 node dist/cli.js ask .yarramate/workspace.yaml "free text about the model"
 node dist/cli.js ask .yarramate/workspace.yaml --subjects
 node dist/cli.js ask .yarramate/workspace.yaml --advise "a design question"
+node dist/cli.js ask .yarramate/workspace.yaml --where "compiler"
 node dist/cli.js check .yarramate/workspace.yaml --json
 node dist/cli.js reconcile .yarramate/workspace.yaml
 node dist/cli.js export graph .yarramate/workspace.yaml

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,12 +3,12 @@ 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';
 import { compileWorkspaceWithProfileContext, } from './compiler.js';
-import { evaluateEvidenceWorkspace, loadEvidence } from './evidence.js';
+import { evaluateEvidenceWorkspace, loadEvidence, } from './evidence.js';
 import { evaluateCatalogue, loadQuestionCatalogue, renderInterrogationReport, } from './interrogate-command.js';
 import { buildNextSubjects, coverageClause, } from './next-command.js';
 import { conceptKinds, relationshipPolicies, } from './profile.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;
@@ -124,9 +224,11 @@ export function runAskCommand(options, cwd) {
     let open = false;
     let kinds = false;
     let advise = false;
+    let where = false;
     let compare;
     let changed;
     let budget;
+    let neighbours;
     let kindFilter;
     let statusFilter;
     let cataloguePath;
@@ -157,6 +259,10 @@ export function runAskCommand(options, cwd) {
             advise = true;
             continue;
         }
+        if (option === '--where') {
+            where = true;
+            continue;
+        }
         if (option === '--compare') {
             const from = options[index + 1];
             const to = options[index + 2];
@@ -172,6 +278,7 @@ export function runAskCommand(options, cwd) {
             continue;
         }
         if (option === '--budget' ||
+            option === '--neighbours' ||
             option === '--kind' ||
             option === '--status' ||
             option === '--catalogue' ||
@@ -186,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 };
@@ -231,13 +344,24 @@ export function runAskCommand(options, cwd) {
         exclusiveModes > 1 ||
         (advise && exclusiveModes > 0) ||
         (advise && query.length === 0) ||
+        (where &&
+            (exclusiveModes > 0 ||
+                advise ||
+                changed !== undefined ||
+                budget !== undefined ||
+                neighbours !== undefined ||
+                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 && changed === undefined)))) {
+            (json || (query.length === 0 && !advise && changed === undefined))) ||
+        (neighbours !== undefined &&
+            query.length === 0 &&
+            !advise &&
+            changed === undefined)) {
         return { exitCode: 2, stdout: '', stderr: usage };
     }
     try {
@@ -604,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,
@@ -613,6 +737,7 @@ export function runAskCommand(options, cwd) {
                 seeds,
                 changed: derived.changed,
                 coverage,
+                ...(neighbourhood === undefined ? {} : { neighbourhood }),
                 result: evaluated,
             };
             if (changedIds.length === 0) {
@@ -626,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.`
@@ -638,11 +766,25 @@ export function runAskCommand(options, cwd) {
         // names a projection file is precise addressing; anything else runs
         // through free-text seeding, where exact subject ids win.
         const soleTerm = query.length === 1 ? query[0] : undefined;
-        const projectionCandidate = soleTerm !== undefined && !advise && existsSync(resolve(cwd, soleTerm))
+        const projectionCandidate = soleTerm !== undefined &&
+            !advise &&
+            !where &&
+            existsSync(resolve(cwd, soleTerm))
             ? resolve(cwd, soleTerm)
             : 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'),
@@ -672,7 +814,93 @@ export function runAskCommand(options, cwd) {
                     `List the roster: yarramate ask ${workspacePath} --subjects\n`,
             };
         }
-        const evaluated = sliceProjection(graph, resolution.seeds, topic, compilation.profileContext);
+        // --where: evidence-backed pointing (ADR 0068). Verified locations for
+        // the matched subjects, an explicit list of matched-but-unobserved
+        // subjects, and a hand-off note for everything outside the model —
+        // authority follows epistemic status, so the routing is stated in the
+        // output rather than assumed by the reader.
+        if (where) {
+            const evidenceDocuments = [];
+            for (const path of workspace.evidence) {
+                const loaded = loadEvidence({
+                    path,
+                    source: readFileSync(resolve(cwd, path), 'utf8'),
+                });
+                if (!loaded.ok)
+                    return failed(loaded.diagnostics);
+                evidenceDocuments.push(loaded.evidence);
+            }
+            const subjectOf = (observation) => 'subject' in observation
+                ? observation.subject
+                : (observation.claim.split('~')[0] ?? observation.claim);
+            // Subject- and claim-level observations often share a locator; the
+            // pointer is the same either way, so identical entries collapse.
+            const entriesBySeed = resolution.seeds.map((seed) => ({
+                subject: seed,
+                observations: [
+                    ...new Map(evidenceDocuments
+                        .flatMap((document) => document.observations
+                        .filter((observation) => subjectOf(observation) === seed)
+                        .map((observation) => ({
+                        uri: observation.evidence.uri,
+                        result: observation.result,
+                        provider: document.provider,
+                        ...(observation.evidence.message === undefined
+                            ? {}
+                            : { message: observation.evidence.message }),
+                    })))
+                        .map((entry) => [
+                        `${entry.uri}${entry.result}${entry.provider}${entry.message ?? ''}`,
+                        entry,
+                    ])).values(),
+                ].sort((left, right) => left.uri.localeCompare(right.uri) ||
+                    left.result.localeCompare(right.result)),
+            }));
+            const located = entriesBySeed.filter(({ observations }) => observations.length > 0);
+            const unobserved = entriesBySeed
+                .filter(({ observations }) => observations.length === 0)
+                .map(({ subject }) => subject);
+            const note = workspace.evidence.length === 0
+                ? 'This workspace declares no evidence overlay, so no location is verified. For code locations, use your search tools; author evidence observations to make locations verifiable.'
+                : 'Locations above are verified by evidence overlays. Subjects listed as unobserved are modeled but unlocated. For code outside the model, use your search tools or a code index.';
+            const result = {
+                format: 'yarramate/ask-result/v1',
+                workspace: workspace.id,
+                mode: 'where',
+                addressing: resolution.addressing,
+                topic,
+                seeds: resolution.seeds,
+                matched: resolution.matched,
+                located,
+                coverage: { unobserved, note },
+            };
+            const lines = [
+                `Where: "${topic}" — ${plural(resolution.matched, 'concept')} matched` +
+                    (resolution.matched > resolution.seeds.length
+                        ? `, seeded from the top ${resolution.seeds.length}`
+                        : '') +
+                    `: ${resolution.seeds.join(', ')}`,
+                '',
+            ];
+            for (const entry of located) {
+                lines.push(`  ${entry.subject}`);
+                for (const observation of entry.observations) {
+                    lines.push(`    ${observation.result}  ${observation.uri}  (${observation.provider})`);
+                    if (observation.message !== undefined) {
+                        lines.push(`      ${observation.message}`);
+                    }
+                }
+            }
+            if (located.length === 0) {
+                lines.push('  no verified locations');
+            }
+            if (unobserved.length > 0) {
+                lines.push('', `  unobserved — modeled, no evidence: ${unobserved.join(', ')}`);
+            }
+            lines.push('', note);
+            return emit(result, `${lines.join('\n')}\n`);
+        }
+        const { result: evaluated, neighbourhood } = sliceProjection(graph, resolution.seeds, topic, compilation.profileContext, neighbours ?? defaultNeighbourCap);
         if (!advise) {
             const result = {
                 format: 'yarramate/ask-result/v1',
@@ -682,6 +910,7 @@ export function runAskCommand(options, cwd) {
                 topic,
                 seeds: resolution.seeds,
                 matched: resolution.matched,
+                ...(neighbourhood === undefined ? {} : { neighbourhood }),
                 result: evaluated,
             };
             const rendered = budget === undefined
@@ -694,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
@@ -774,6 +1005,7 @@ export function runAskCommand(options, cwd) {
             seeds: resolution.seeds,
             matched: resolution.matched,
             slice: brief,
+            ...(neighbourhood === undefined ? {} : { neighbourhood }),
             openQuestions,
             ...(reconciliation === undefined ? {} : { reconciliation }),
         };
@@ -784,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> --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> --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.12.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

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://yarrasys.dev/schema/yarramate-ask-result.schema.json",
   "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.",
+  "description": "One envelope for every consumed-now read: orientation, roster, slice, advice, verified locations, next, open questions, and state comparison, discriminated by mode.",
   "type": "object",
   "required": [
     "format",
@@ -23,6 +23,7 @@
         "roster",
         "slice",
         "advice",
+        "where",
         "next",
         "open",
         "compare",
@@ -262,6 +263,9 @@
             }
           },
           "additionalProperties": false
+        },
+        "neighbourhood": {
+          "$ref": "#/$defs/neighbourhoodOmission"
         }
       },
       "additionalProperties": false
@@ -301,6 +305,9 @@
           "type": "string",
           "minLength": 1
         },
+        "neighbourhood": {
+          "$ref": "#/$defs/neighbourhoodOmission"
+        },
         "openQuestions": {
           "type": "array",
           "items": {
@@ -363,6 +370,119 @@
       },
       "additionalProperties": false
     },
+    {
+      "type": "object",
+      "required": [
+        "mode",
+        "addressing",
+        "topic",
+        "seeds",
+        "matched",
+        "located",
+        "coverage"
+      ],
+      "properties": {
+        "format": true,
+        "workspace": true,
+        "mode": {
+          "const": "where"
+        },
+        "addressing": {
+          "enum": [
+            "free-text",
+            "subjects"
+          ]
+        },
+        "topic": {
+          "type": "string",
+          "minLength": 1
+        },
+        "seeds": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "matched": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "located": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "subject",
+              "observations"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "subject": {
+                "type": "string",
+                "minLength": 1
+              },
+              "observations": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "object",
+                  "required": [
+                    "uri",
+                    "result",
+                    "provider"
+                  ],
+                  "additionalProperties": false,
+                  "properties": {
+                    "uri": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "result": {
+                      "enum": [
+                        "confirmed",
+                        "contradicted",
+                        "unknown",
+                        "not-observed"
+                      ]
+                    },
+                    "provider": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "message": {
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "coverage": {
+          "type": "object",
+          "required": [
+            "unobserved",
+            "note"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "unobserved": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "note": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        }
+      }
+    },
     {
       "type": "object",
       "required": [
@@ -593,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/SKILL.md

@@ -33,7 +33,10 @@ design questions, and the backlog — planned subjects in dependency
 order. `ask <workspace.yaml> --subjects` lists every concept;
 `ask <workspace.yaml> --kinds` lists the declarable vocabulary;
 `ask <workspace.yaml> "<free text>"` returns the model slice matching
-your words.
+your words; `ask <workspace.yaml> --where "<free text>"` returns the
+evidence-verified code locations of matching subjects — prefer those
+over searching when the subject is modeled, and use your own search
+tools beyond the coverage boundary the output states.
 
 - Existing implementation is the starting point: follow **Discover an
   existing project**.

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