yarramate 1.5.0 → 1.7.0

package/dist/adapters/visual/session-server.js

@@ -124,6 +124,28 @@ const shippedCatalogue = (() => {
         return undefined;
     }
 })();
+/**
+ * The shipped catalogue plus the ones the workspace carries (#345, ADR 0129).
+ *
+ * A catalogue that cannot be read is SKIPPED rather than failing the session,
+ * which is what the shipped one already did: an interrogation overlay is a
+ * garnish on a model, and losing a session over it would be worse than losing
+ * the questions. `check` is where a broken catalogue is refused.
+ */
+const catalogueSetFor = (workspace) => {
+    if (shippedCatalogue === undefined)
+        return [];
+    const carried = [];
+    for (const path of workspace.questions ?? []) {
+        try {
+            carried.push({ path, source: readFileSync(path, "utf8") });
+        }
+        catch {
+            // Skipped, as above.
+        }
+    }
+    return [shippedCatalogue, ...carried];
+};
 /**
  * Takes one session terminal, whatever caused it: a reviewer's End, a child
  * that failed, a browser that never came back, a cancelling main agent, or a
@@ -612,7 +634,11 @@ export const startVisualServer = async (options) => {
                 // that. A staged view operation pins against these (ADR 0103), and a
                 // projection missing from the map is one the commit will create.
                 projectionDigests: projectionDigestsNow(),
-            }, shippedCatalogue);
+                // The shipped catalogue plus whatever this workspace carries (#345),
+                // so the pane asks the interview `design` asks over the same files.
+                // Read on each recompile rather than once per process, because a
+                // consultant authoring a question mid-session is the whole point.
+            }, catalogueSetFor(resolvedWorkspace));
             // Closures below retain this array, so refresh its contents without
             // replacing the identity the session started with.
             views.splice(0, views.length, ...workspaceModel.views);

package/dist/adapters/visual/workspace-model.d.ts

@@ -57,10 +57,20 @@ export interface DismissedQuestion {
 export declare const interrogationOverlayOf: (compiled: {
     readonly graph: SemanticGraph;
     readonly profileContext: ResolvedProfileContext;
-}, catalogue: {
+}, 
+/**
+ * The catalogue, or the composed SET a workspace carries (#345, ADR 0129).
+ * A set rather than one document so the pane asks the same interview the
+ * CLI does over the same workspace: an editor showing fewer questions than
+ * `design` does over the same files is a disagreement with no symptom.
+ */
+catalogue: {
     readonly path: string;
     readonly source: string;
-}, 
+} | readonly {
+    readonly path: string;
+    readonly source: string;
+}[], 
 /**
  * What the host has already dealt with (#328). Evaluation is unchanged and
  * the model is untouched: this decides only what the pane draws, because a
@@ -83,7 +93,10 @@ export declare const renderedWorkspaceOf: (compiled: {
 }, views: readonly VisualViewSummary[], metadata: Omit<VisualRenderedModel, "graph" | "vocabulary" | "interrogation">, catalogue?: {
     readonly path: string;
     readonly source: string;
-}, dismissed?: readonly DismissedQuestion[]) => {
+} | readonly {
+    readonly path: string;
+    readonly source: string;
+}[], dismissed?: readonly DismissedQuestion[]) => {
     readonly model: VisualRenderedModel;
     readonly views: readonly VisualViewSummary[];
 };

package/dist/adapters/visual/workspace-model.js

@@ -6,7 +6,7 @@ import { projectGraphForCanvas } from "../../graph-projection.js";
 import { DEFAULT_PROJECTION_DIRECTORY } from "./view-identity.js";
 import { evaluateProjection, explainProjection } from "../../projection.js";
 import { kindLabelOf } from "../../kind-label.js";
-import { evaluateCatalogue, loadQuestionCatalogue, } from "../../interrogate-command.js";
+import { evaluateCatalogue, composeCatalogues, } from "../../interrogate-command.js";
 /**
  * What a workspace looks like to the editor, however the editor is being run
  * (#252).
@@ -46,7 +46,14 @@ export const kindOptionsOf = (lineages) => [...lineages.keys()].map((id) => ({
  * them would read as five, and the reviewer counting boxes would find three.
  */
 export const conceptCountOf = (graph, query, profileContext) => evaluateProjection(graph, adHoc(query), profileContext).subjects.filter(({ type }) => type === "concept").length;
-export const interrogationOverlayOf = (compiled, catalogue, 
+export const interrogationOverlayOf = (compiled, 
+/**
+ * The catalogue, or the composed SET a workspace carries (#345, ADR 0129).
+ * A set rather than one document so the pane asks the same interview the
+ * CLI does over the same workspace: an editor showing fewer questions than
+ * `design` does over the same files is a disagreement with no symptom.
+ */
+catalogue, 
 /**
  * What the host has already dealt with (#328). Evaluation is unchanged and
  * the model is untouched: this decides only what the pane draws, because a
@@ -54,10 +61,10 @@ export const interrogationOverlayOf = (compiled, catalogue,
  * a pane embedded in it.
  */
 dismissed = []) => {
-    const loaded = loadQuestionCatalogue(catalogue);
-    if (!loaded.ok)
+    const composed = composeCatalogues(Array.isArray(catalogue) ? catalogue : [catalogue]);
+    if (!composed.ok)
         return undefined;
-    const report = evaluateCatalogue(loaded.catalogue, compiled.graph, compiled.profileContext);
+    const report = evaluateCatalogue(composed.composed.catalogue, compiled.graph, compiled.profileContext, undefined, composed.composed.catalogues);
     const dismissedEverywhere = new Set(dismissed
         .filter(({ subject }) => subject === undefined)
         .map(({ questionId }) => questionId));

package/dist/ask-command.js

@@ -9,7 +9,8 @@ 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 { evaluateCatalogue, loadQuestionCatalogue, renderInterrogationReport, } from './interrogate-command.js';
+import { catalogueSources } from './catalogue-sources.js';
+import { evaluateCatalogue, composeCatalogues, renderInterrogationReport, } from './interrogate-command.js';
 import { buildNextSubjects, coverageClause, } from './next-command.js';
 import { conceptKinds, relationshipPolicies, } from './profile.js';
 import { ARCHIMATE_RELATIONSHIPS_VERSION, CORE_CONCEPT_KIND_ORDER, PERMITTED_RELATIONSHIP_LETTERS, RELATIONSHIP_LETTERS, } from './archimate-relationships.generated.js';
@@ -468,13 +469,13 @@ export function runAskCommand(options, cwd) {
             const planned = buildNextSubjects(wholeWorkspace, compilation.graph, compilation.profileContext, evaluation.reports);
             const current = entries.filter(({ status }) => status === 'current');
             const retired = entries.filter(({ status }) => status === 'retired');
-            const loadedCatalogue = loadQuestionCatalogue({
+            const composed = composeCatalogues(catalogueSources({
                 path: shippedCataloguePath,
                 source: readFileSync(shippedCataloguePath, 'utf8'),
-            }, compilation.profileContext);
-            if (!loadedCatalogue.ok)
-                return failed(loadedCatalogue.diagnostics);
-            const report = evaluateCatalogue(loadedCatalogue.catalogue, compilation.graph, compilation.profileContext, evidenceDocuments.flatMap(({ observations }) => observations));
+            }, workspace, cwd), compilation.profileContext);
+            if (!composed.ok)
+                return failed(composed.diagnostics);
+            const report = evaluateCatalogue(composed.composed.catalogue, compilation.graph, compilation.profileContext, evidenceDocuments.flatMap(({ observations }) => observations), composed.composed.catalogues);
             const result = {
                 format: 'yarramate/ask-result/v1',
                 workspace: workspace.id,
@@ -698,12 +699,12 @@ export function runAskCommand(options, cwd) {
             const resolvedCataloguePath = cataloguePath === undefined
                 ? shippedCataloguePath
                 : resolve(cwd, cataloguePath);
-            const loadedCatalogue = loadQuestionCatalogue({
+            const composed = composeCatalogues(catalogueSources({
                 path: cataloguePath ?? resolvedCataloguePath,
                 source: readFileSync(resolvedCataloguePath, 'utf8'),
-            }, compilation.profileContext);
-            if (!loadedCatalogue.ok)
-                return failed(loadedCatalogue.diagnostics);
+            }, workspace, cwd), compilation.profileContext);
+            if (!composed.ok)
+                return failed(composed.diagnostics);
             // The evidence overlay rides along for the one condition that
             // reads it (unchallenged-evidence); a workspace declaring no
             // evidence passes an overlay known to be empty.
@@ -718,13 +719,21 @@ export function runAskCommand(options, cwd) {
                 evidenceObservations.push(...loaded.evidence.observations);
             }
             const report = {
-                ...evaluateCatalogue(loadedCatalogue.catalogue, graph, compilation.profileContext, evidenceObservations),
+                ...evaluateCatalogue(composed.composed.catalogue, graph, compilation.profileContext, evidenceObservations, composed.composed.catalogues),
                 workspace: workspace.id,
             };
+            // Field by field, to fix key ORDER in the emitted JSON. Every optional
+            // field has to be threaded through explicitly, which is why `catalogues`
+            // is here: a copier like this drops a new field silently and the only
+            // symptom is an absent one, which reads as "did not apply" rather than
+            // as "was lost".
             const ordered = {
                 format: report.format,
                 workspace: report.workspace,
                 catalogue: report.catalogue,
+                ...(report.catalogues === undefined
+                    ? {}
+                    : { catalogues: report.catalogues }),
                 semantics: report.semantics,
                 summary: report.summary,
                 waves: report.waves,
@@ -993,12 +1002,12 @@ export function runAskCommand(options, cwd) {
         const resolvedCataloguePath = cataloguePath === undefined
             ? shippedCataloguePath
             : resolve(cwd, cataloguePath);
-        const loadedCatalogue = loadQuestionCatalogue({
+        const composed = composeCatalogues(catalogueSources({
             path: cataloguePath ?? resolvedCataloguePath,
             source: readFileSync(resolvedCataloguePath, 'utf8'),
-        }, compilation.profileContext);
-        if (!loadedCatalogue.ok)
-            return failed(loadedCatalogue.diagnostics);
+        }, workspace, cwd), compilation.profileContext);
+        if (!composed.ok)
+            return failed(composed.diagnostics);
         // Loaded ahead of evaluation so the overlay feeds the one condition
         // that reads it (unchallenged-evidence), then reused for the
         // reconciliation summary below.
@@ -1012,7 +1021,7 @@ export function runAskCommand(options, cwd) {
                 return failed(loaded.diagnostics);
             evidenceDocuments.push(loaded.evidence);
         }
-        const report = evaluateCatalogue(loadedCatalogue.catalogue, graph, compilation.profileContext, evidenceDocuments.flatMap(({ observations }) => observations));
+        const report = evaluateCatalogue(composed.composed.catalogue, graph, compilation.profileContext, evidenceDocuments.flatMap(({ observations }) => observations), composed.composed.catalogues);
         const openQuestions = [];
         for (const wave of report.waves) {
             for (const question of wave.questions) {

package/dist/catalogue-sources.d.ts

@@ -0,0 +1,20 @@
+import type { WorkspaceSource } from './compiler.js';
+import type { ResolvedWorkspace } from './workspace.js';
+export declare const shippedCataloguePath: string;
+/** The base catalogue as a source, read from disk. */
+export declare const shippedCatalogueSource: () => WorkspaceSource;
+/**
+ * The catalogues a verb should compose: the base, then whatever the workspace
+ * carries (#345, ADR 0129).
+ *
+ * Built in ONE place because every verb that interviews has to make the same
+ * choice, and a verb that forgot the workspace half would silently ask fewer
+ * questions than the workspace declares - a failure with no symptom, which is
+ * the shape this repository keeps being bitten by.
+ *
+ * The base is REPLACED by `--catalogue` and ADDED TO by `questions:`. Those
+ * are different powers on purpose: a host controls the catalogue that is not
+ * in the workspace (#328), and a consultant adds to it mid-engagement without
+ * a product release.
+ */
+export declare const catalogueSources: (base: WorkspaceSource, workspace: Pick<ResolvedWorkspace, 'questions'>, cwd: string) => readonly WorkspaceSource[];

package/dist/catalogue-sources.js

@@ -0,0 +1,39 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// The catalogue ships inside the package, versioned with it, and harnesses
+// never pass catalogue paths. The relative hop works from both src/ (dev) and
+// dist/ (shipped). Defined ONCE: `design`, `ask` and `check` all need it, and
+// three copies of a path constant is three chances for them to disagree about
+// which catalogue is the base.
+const here = dirname(fileURLToPath(import.meta.url));
+export const shippedCataloguePath = join(here, '..', 'catalogues', 'core-enrichment.yaml');
+/** The base catalogue as a source, read from disk. */
+export const shippedCatalogueSource = () => ({
+    path: shippedCataloguePath,
+    source: readFileSync(shippedCataloguePath, 'utf8'),
+});
+/**
+ * The catalogues a verb should compose: the base, then whatever the workspace
+ * carries (#345, ADR 0129).
+ *
+ * Built in ONE place because every verb that interviews has to make the same
+ * choice, and a verb that forgot the workspace half would silently ask fewer
+ * questions than the workspace declares - a failure with no symptom, which is
+ * the shape this repository keeps being bitten by.
+ *
+ * The base is REPLACED by `--catalogue` and ADDED TO by `questions:`. Those
+ * are different powers on purpose: a host controls the catalogue that is not
+ * in the workspace (#328), and a consultant adds to it mid-engagement without
+ * a product release.
+ */
+export const catalogueSources = (base, workspace, cwd) => [
+    base,
+    // `?? []` because `questions` is optional on the published type: adding a
+    // required field to `ResolvedWorkspace` broke a consumer's production module
+    // once already.
+    ...(workspace.questions ?? []).map((path) => ({
+        path,
+        source: readFileSync(resolve(cwd, path), 'utf8'),
+    })),
+];

package/dist/check-command.js

@@ -1,13 +1,15 @@
 import { existsSync, readFileSync } from 'node:fs';
+import { catalogueSources, shippedCatalogueSource, } from './catalogue-sources.js';
+import { composeCatalogues } from './interrogate-command.js';
 import { resolve } from 'node:path';
 import Ajv2020Module from 'ajv/dist/2020.js';
 import { parseDocument } from 'yaml';
 import { loadAdapterMapping, validateAdapterMappings, } from './adapter-mapping.js';
 import { checkResultJson, humanDiagnostics, resolveCliWorkspaceSources, sortDiagnostics, usage, } from './cli-support.js';
-import { compileWorkspace, withDiagnosticSubjects } from './compiler.js';
+import { compileWorkspaceWithProfileContext, withDiagnosticSubjects, } from './compiler.js';
 import { checkCoreContract, loadCoreContract, } from './core-contract.js';
 import { evaluateEvidenceWorkspace, loadEvidence, } from './evidence.js';
-import { loadProjection } from './projection.js';
+import { loadProjection, projectionReferenceDiagnostics, } from './projection.js';
 import { reconcileEvidenceReports, } from './reconciliation.js';
 // `.default ?? module`, not a bare `.default`: NodeNext sees the raw CJS
 // `module.exports` and a bundler the unwrapped class. One shape for all of
@@ -138,13 +140,15 @@ export function runCheckCommand(options, cwd) {
                 : humanDiagnostics(contractDiagnostics);
             return { exitCode: 1, stdout: output, stderr: '' };
         }
-        const projectionDiagnostics = sortDiagnostics(resolved.projections.flatMap((path) => {
-            const loaded = loadProjection({
-                path,
-                source: readFileSync(resolve(cwd, path), 'utf8'),
-            });
-            return loaded.ok ? [] : loaded.diagnostics;
+        const projectionSources = resolved.projections.map((path) => ({
+            path,
+            source: readFileSync(resolve(cwd, path), 'utf8'),
+        }));
+        const loadedProjections = projectionSources.map((source) => ({
+            source,
+            loaded: loadProjection(source),
         }));
+        const projectionDiagnostics = sortDiagnostics(loadedProjections.flatMap(({ loaded }) => loaded.ok ? [] : loaded.diagnostics));
         if (projectionDiagnostics.length > 0) {
             const output = json
                 ? checkResultJson(false, projectionDiagnostics)
@@ -177,7 +181,7 @@ export function runCheckCommand(options, cwd) {
                 : humanDiagnostics(mappingLoadDiagnostics);
             return { exitCode: 1, stdout: output, stderr: '' };
         }
-        const result = compileWorkspace(coreSources);
+        const result = compileWorkspaceWithProfileContext(coreSources);
         const mappingValidation = result.ok
             ? validateAdapterMappings(result.graph, loadedMappings.flatMap((loaded) => loaded.ok ? [loaded.mapping] : []))
             : undefined;
@@ -190,9 +194,34 @@ export function runCheckCommand(options, cwd) {
         const evidenceDiagnostics = evidenceEvaluation === undefined || evidenceEvaluation.ok
             ? []
             : evidenceEvaluation.diagnostics;
+        // A catalogue the manifest declares is workspace content, so `check`
+        // refuses a broken one (#345, ADR 0129). Composed rather than checked one
+        // by one, because the refusals that matter are CROSS-catalogue: a wave
+        // declared twice, and a question naming a wave nothing in the set
+        // declares. Checking each file alone would miss both and would refuse the
+        // one thing the feature exists to allow, a question joining a wave another
+        // catalogue declared.
+        const catalogueDiagnostics = result.ok && resolved.questions.length > 0
+            ? (() => {
+                const composed = composeCatalogues(catalogueSources(shippedCatalogueSource(), resolved, cwd), result.profileContext);
+                return composed.ok ? [] : composed.diagnostics;
+            })()
+            : [];
+        // A projection is a document, and a query holds references the same way a
+        // relationship does. Checked HERE rather than with the projection's own
+        // schema load above, because a reference can only be resolved against a
+        // model that compiled: reporting dangling names out of a workspace that
+        // does not build would bury the real failure under its consequences.
+        const referenceDiagnostics = result.ok
+            ? loadedProjections.flatMap(({ source, loaded }) => loaded.ok
+                ? projectionReferenceDiagnostics(source, loaded.projection, result.graph, result.profileContext)
+                : [])
+            : [];
         const optionalDiagnostics = sortDiagnostics([
             ...mappingDiagnostics,
             ...evidenceDiagnostics,
+            ...referenceDiagnostics,
+            ...catalogueDiagnostics,
         ]);
         const ok = result.ok && optionalDiagnostics.length === 0;
         // Published results name the subject a diagnostic is about wherever its

package/dist/cli-support.d.ts

@@ -7,7 +7,7 @@ export interface CliResult {
 export declare const isMainModule: (moduleUrl: string, entrypoint: string | undefined) => boolean;
 export declare const packageVersion: string;
 export declare const versionResult: (binary: string) => CliResult;
-export declare const usage = "Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate design <workspace.yaml> [--subject <subject-id>] [--catalogue <catalogue.yaml>] [--facilitate] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> \"<free text>\" | <subject-id> ... | <projection.yaml> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate ask <workspace.yaml> --subjects [--kind <term>] [--status <status>] [--json]\n  yarramate ask <workspace.yaml> --kinds [--json]\n  yarramate ask <workspace.yaml> --advise \"<topic>\" [--budget <tokens>] [--neighbours <n>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --where \"<free text>\" | <subject-id> ... [--json]\n  yarramate ask <workspace.yaml> --next [--json]\n  yarramate ask <workspace.yaml> --open [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --compare <from-state> <to-state> [--json]\n  yarramate ask <workspace.yaml> --changed <git-range> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml> [--json]\n  yarramate export graph <workspace.yaml> [--out <file>]\n  yarramate export markdown <projection.yaml> <workspace.yaml> [--out <file>]\n  yarramate export markdown --changed <git-range> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export briefs --changed <git-range> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export rtm <workspace.yaml> --out <directory>\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml> [--changed <git-range>]\n";
+export declare const usage = "Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate design <workspace.yaml> [--subject <subject-id>] [--catalogue <catalogue.yaml>] [--facilitate] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> \"<free text>\" | <subject-id> ... | <projection.yaml> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate ask <workspace.yaml> --subjects [--kind <term>] [--status <status>] [--json]\n  yarramate ask <workspace.yaml> --kinds [--json]\n  yarramate ask <workspace.yaml> --advise \"<topic>\" [--budget <tokens>] [--neighbours <n>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --where \"<free text>\" | <subject-id> ... [--json]\n  yarramate ask <workspace.yaml> --next [--json]\n  yarramate ask <workspace.yaml> --open [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --compare <from-state> <to-state> [--json]\n  yarramate ask <workspace.yaml> --changed <git-range> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml> [--json]\n  yarramate export graph <workspace.yaml> [--out <file>]\n  yarramate export markdown <projection.yaml> <workspace.yaml> [--out <file>]\n  yarramate export markdown --changed <git-range> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export briefs --changed <git-range> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export rtm <workspace.yaml> --out <directory>\n  yarramate export xlsx <projection.yaml> <workspace.yaml> --out <file>\n  yarramate import xlsx <workbook.xlsx> <workspace.yaml> [--json]\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml> [--changed <git-range>]\n";
 export declare const diagnosticJson: (diagnostics: unknown) => string;
 export declare const checkResultJson: (ok: boolean, diagnostics: unknown, counted?: {
     readonly documents: number;
@@ -30,6 +30,13 @@ export declare const resolveCliWorkspaceSources: (paths: readonly string[], cwd:
     readonly contracts: readonly string[];
     /** Pattern documents, which ride in `paths` and are not documents. */
     readonly patterns: readonly string[];
+    /**
+     * Question catalogues the workspace carries (#345). Handed over rather
+     * than resolved-and-dropped, which is the #268 failure recorded below:
+     * a category a manifest declares and no verb receives is ignored with
+     * no symptom.
+     */
+    readonly questions: readonly string[];
 } | {
     readonly ok: false;
     readonly diagnostics: readonly Diagnostic[];

package/dist/cli-support.js

@@ -22,7 +22,7 @@ export const versionResult = (binary) => ({
     stdout: `${binary} ${packageVersion}\n`,
     stderr: '',
 });
-export const usage = 'Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate design <workspace.yaml> [--subject <subject-id>] [--catalogue <catalogue.yaml>] [--facilitate] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> "<free text>" | <subject-id> ... | <projection.yaml> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate ask <workspace.yaml> --subjects [--kind <term>] [--status <status>] [--json]\n  yarramate ask <workspace.yaml> --kinds [--json]\n  yarramate ask <workspace.yaml> --advise "<topic>" [--budget <tokens>] [--neighbours <n>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --where "<free text>" | <subject-id> ... [--json]\n  yarramate ask <workspace.yaml> --next [--json]\n  yarramate ask <workspace.yaml> --open [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --compare <from-state> <to-state> [--json]\n  yarramate ask <workspace.yaml> --changed <git-range> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml> [--json]\n  yarramate export graph <workspace.yaml> [--out <file>]\n  yarramate export markdown <projection.yaml> <workspace.yaml> [--out <file>]\n  yarramate export markdown --changed <git-range> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export briefs --changed <git-range> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export rtm <workspace.yaml> --out <directory>\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml> [--changed <git-range>]\n';
+export const usage = 'Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate design <workspace.yaml> [--subject <subject-id>] [--catalogue <catalogue.yaml>] [--facilitate] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> "<free text>" | <subject-id> ... | <projection.yaml> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate ask <workspace.yaml> --subjects [--kind <term>] [--status <status>] [--json]\n  yarramate ask <workspace.yaml> --kinds [--json]\n  yarramate ask <workspace.yaml> --advise "<topic>" [--budget <tokens>] [--neighbours <n>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --where "<free text>" | <subject-id> ... [--json]\n  yarramate ask <workspace.yaml> --next [--json]\n  yarramate ask <workspace.yaml> --open [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --compare <from-state> <to-state> [--json]\n  yarramate ask <workspace.yaml> --changed <git-range> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml> [--json]\n  yarramate export graph <workspace.yaml> [--out <file>]\n  yarramate export markdown <projection.yaml> <workspace.yaml> [--out <file>]\n  yarramate export markdown --changed <git-range> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export briefs --changed <git-range> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export rtm <workspace.yaml> --out <directory>\n  yarramate export xlsx <projection.yaml> <workspace.yaml> --out <file>\n  yarramate import xlsx <workbook.xlsx> <workspace.yaml> [--json]\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml> [--changed <git-range>]\n';
 export const diagnosticJson = (diagnostics) => `${JSON.stringify({
     format: 'yarramate/diagnostic-result/v1',
     diagnostics,
@@ -51,6 +51,7 @@ export const resolveCliWorkspaceSources = (paths, cwd, options = {}) => {
             evidence: [],
             contracts: [],
             patterns: [],
+            questions: [],
         };
     }
     const manifestPath = paths[0];
@@ -62,6 +63,7 @@ export const resolveCliWorkspaceSources = (paths, cwd, options = {}) => {
             evidence: [],
             contracts: [],
             patterns: [],
+            questions: [],
         };
     }
     const source = readFileSync(resolve(cwd, manifestPath), 'utf8');
@@ -73,6 +75,7 @@ export const resolveCliWorkspaceSources = (paths, cwd, options = {}) => {
             evidence: [],
             contracts: [],
             patterns: [],
+            questions: [],
         };
     }
     const loaded = loadWorkspaceManifest({ path: manifestPath, source }, cwd);
@@ -99,6 +102,7 @@ export const resolveCliWorkspaceSources = (paths, cwd, options = {}) => {
             evidence: loaded.workspace.evidence,
             contracts: loaded.workspace.contracts,
             patterns: loaded.workspace.patterns,
+            questions: loaded.workspace.questions ?? [],
         }
         : { ok: false, diagnostics: loaded.diagnostics };
 };

package/dist/cli.d.ts

@@ -3,3 +3,13 @@ import { type CliResult } from './cli-support.js';
 export type { CliResult } from './cli-support.js';
 export declare const deriveInitId: (directory: string) => string;
 export declare function runCli(args: readonly string[], cwd?: string): CliResult;
+/**
+ * Every verb, including the one that cannot be synchronous.
+ *
+ * `import xlsx` has to inflate a workbook, and the only inflater available
+ * everywhere this runs is `DecompressionStream`, which is async. Widening
+ * `runCli` to return a promise would change the type every one of its callers
+ * reads - the readers half of the rule in CONTRIBUTING.md - so the async verb
+ * gets its own entry and `runCli` keeps its signature.
+ */
+export declare function runCliAsync(args: readonly string[], cwd?: string): Promise<CliResult>;

package/dist/cli.js

@@ -5,6 +5,7 @@ import { compileWorkspace } from './compiler.js';
 import { diagnosticJson, isMainModule, usage, versionResult, } from './cli-support.js';
 import { runAskCommand } from './ask-command.js';
 import { runCheckCommand } from './check-command.js';
+import { runImportCommand } from './import-command.js';
 import { runExportCommand } from './export-command.js';
 import { runApplyCommand } from './apply-cli.js';
 import { runDesignCommand } from './design-command.js';
@@ -227,8 +228,23 @@ export function runCli(args, cwd = process.cwd()) {
     }
     return { exitCode: 2, stdout: '', stderr: usage };
 }
+/**
+ * Every verb, including the one that cannot be synchronous.
+ *
+ * `import xlsx` has to inflate a workbook, and the only inflater available
+ * everywhere this runs is `DecompressionStream`, which is async. Widening
+ * `runCli` to return a promise would change the type every one of its callers
+ * reads - the readers half of the rule in CONTRIBUTING.md - so the async verb
+ * gets its own entry and `runCli` keeps its signature.
+ */
+export async function runCliAsync(args, cwd = process.cwd()) {
+    const [command, ...options] = args;
+    if (command === 'import')
+        return runImportCommand(options, cwd);
+    return runCli(args, cwd);
+}
 if (isMainModule(import.meta.url, process.argv[1])) {
-    const result = runCli(process.argv.slice(2));
+    const result = await runCliAsync(process.argv.slice(2));
     process.stdout.write(result.stdout);
     process.stderr.write(result.stderr);
     process.exitCode = result.exitCode;

package/dist/design-command.js

@@ -5,7 +5,7 @@ import { parseDocument } from 'yaml';
 import { diagnosticJson, humanDiagnostics, usage, } from './cli-support.js';
 import { compileWorkspaceWithProfileContext, } from './compiler.js';
 import { loadEvidence } from './evidence.js';
-import { evaluateCatalogue, loadQuestionCatalogue, renderQuestion, } from './interrogate-command.js';
+import { composeCatalogues, evaluateCatalogue, renderQuestion, } from './interrogate-command.js';
 import { evaluateProjection } from './projection.js';
 import { renderBrief } from './brief.js';
 import { loadWorkspaceManifest } from './workspace.js';
@@ -205,12 +205,23 @@ export function runDesignCommand(options, cwd) {
         })));
         if (!compilation.ok)
             return failed(compilation.diagnostics);
-        const loadedCatalogue = loadQuestionCatalogue({
-            path: cataloguePath ?? resolvedCataloguePath,
-            source: readFileSync(resolvedCataloguePath, 'utf8'),
-        }, compilation.profileContext);
-        if (!loadedCatalogue.ok)
-            return failed(loadedCatalogue.diagnostics);
+        // The base, then whatever the workspace carries (#345, ADR 0129). The
+        // base is REPLACED by `--catalogue` and ADDED TO by `questions:`, which is
+        // what lets a consultant author a question mid-engagement with no product
+        // release while a host still controls the catalogue that is not in the
+        // workspace.
+        const composed = composeCatalogues([
+            {
+                path: cataloguePath ?? resolvedCataloguePath,
+                source: readFileSync(resolvedCataloguePath, 'utf8'),
+            },
+            ...(workspace.questions ?? []).map((path) => ({
+                path,
+                source: readFileSync(resolve(cwd, path), 'utf8'),
+            })),
+        ], compilation.profileContext);
+        if (!composed.ok)
+            return failed(composed.diagnostics);
         // The evidence overlay rides along for the one condition that reads
         // it (unchallenged-evidence). A workspace declaring no evidence
         // passes an empty overlay — known to be empty, which keeps that
@@ -235,8 +246,9 @@ export function runDesignCommand(options, cwd) {
                 };
             }
         }
-        const report = evaluateCatalogue(loadedCatalogue.catalogue, compilation.graph, compilation.profileContext, evidenceObservations);
-        const askPlainById = new Map(loadedCatalogue.catalogue.questions.flatMap((question) => question.askPlain === undefined
+        const report = evaluateCatalogue(composed.composed.catalogue, compilation.graph, compilation.profileContext, evidenceObservations, composed.composed.catalogues);
+        // Keyed by the QUALIFIED id, matching what the report now carries.
+        const askPlainById = new Map(composed.composed.catalogue.questions.flatMap((question) => question.askPlain === undefined
             ? []
             : [[question.id, question.askPlain]]));
         const step = selectStep(report, subjectFilter, askPlainById);

package/dist/export-command.js

@@ -1,16 +1,18 @@
 import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseDocument } from 'yaml';
 import { renderBrief } from './brief.js';
 import { deriveChangedSubjects } from './changed.js';
-import { humanDiagnostics, usage } from './cli-support.js';
+import { humanDiagnostics, packageVersion, usage, } from './cli-support.js';
 import { compileWorkspaceWithProfileContext, } from './compiler.js';
 import { serializeSemanticGraph } from './graph.js';
 import { evaluateEvidenceWorkspace, loadEvidence, } from './evidence.js';
 import { evaluateProjection, loadProjection, renderProjectionMarkdown, } from './projection.js';
 import { buildRtm, renderRtmMarkdown } from './rtm.js';
+import { workbookFrom } from './workbook.js';
 import { loadWorkspaceManifest } from './workspace.js';
 // The adapter stays a separate process behind the verb: the core never
 // imports adapter code (the adapter-runtime-dependency exclusion), it
@@ -74,7 +76,7 @@ const parseExportOptions = (options) => {
 export function runExportCommand(options, cwd) {
     const [kind, ...rest] = options;
     if (kind === undefined ||
-        !['graph', 'markdown', 'briefs', 'rtm', 'likec4'].includes(kind)) {
+        !['graph', 'markdown', 'briefs', 'rtm', 'likec4', 'xlsx'].includes(kind)) {
         return { exitCode: 2, stdout: '', stderr: usage };
     }
     const parsed = parseExportOptions(rest);
@@ -128,7 +130,8 @@ export function runExportCommand(options, cwd) {
         parsed.json ||
         (usesChanged && (kind === 'graph' || kind === 'rtm')) ||
         (parsed.budget !== undefined && kind !== 'briefs') ||
-        ((kind === 'briefs' || kind === 'rtm') && parsed.out === undefined)) {
+        ((kind === 'briefs' || kind === 'rtm' || kind === 'xlsx') &&
+            parsed.out === undefined)) {
         return { exitCode: 2, stdout: '', stderr: usage };
     }
     try {
@@ -149,14 +152,17 @@ export function runExportCommand(options, cwd) {
         if (!loadedWorkspace.ok)
             return failed(loadedWorkspace.diagnostics);
         const workspace = loadedWorkspace.workspace;
-        const compilation = compileWorkspaceWithProfileContext([
+        // Named rather than inlined so the workbook can pin its digests against
+        // exactly the bytes that compiled, the way a visual commit does (#355).
+        const sources = [
             ...workspace.profiles,
             ...workspace.patterns,
             ...workspace.documents,
         ].map((path) => ({
             path,
             source: readFileSync(resolve(cwd, path), 'utf8'),
-        })));
+        }));
+        const compilation = compileWorkspaceWithProfileContext(sources);
         if (!compilation.ok)
             return failed(compilation.diagnostics);
         if (kind === 'rtm') {
@@ -246,6 +252,36 @@ export function runExportCommand(options, cwd) {
                 return failed(loadedProjection.diagnostics);
             result = evaluateProjection(compilation.graph, loadedProjection.projection, compilation.profileContext);
         }
+        if (kind === 'xlsx') {
+            // A workbook an architect can work in (#355). It takes a PROJECTION,
+            // like markdown and briefs do, which is what gives it version selection
+            // for free: a projection query already has a `states` facet, so
+            // "export the target state" is an existing capability rather than a
+            // flag competing with it.
+            const bytes = workbookFrom(result, {
+                workspace: workspace.id,
+                yarramateVersion: packageVersion,
+                sourceDigests: Object.fromEntries(sources.map(({ path, source }) => [
+                    path,
+                    createHash('sha256').update(source, 'utf8').digest('hex'),
+                ])),
+                conceptKinds: [
+                    ...compilation.profileContext.conceptKindLineages.keys(),
+                ].sort(),
+                relationshipKinds: [
+                    ...compilation.profileContext.relationshipKindLineages.keys(),
+                ].sort(),
+                statuses: ['planned', 'current', 'retired'],
+            });
+            const outPath = resolve(cwd, parsed.out);
+            mkdirSync(dirname(outPath), { recursive: true });
+            writeFileSync(outPath, bytes);
+            return {
+                exitCode: 0,
+                stdout: `Wrote workbook to ${parsed.out}\n`,
+                stderr: '',
+            };
+        }
         if (kind === 'markdown') {
             const rendered = renderProjectionMarkdown(result, compilation.profileContext);
             if (parsed.out === undefined) {