spexcode 0.6.1 → 0.6.5

package/node_modules/@spexcode/spec-cli/dist/guidance-catalog.d.ts

@@ -0,0 +1,64 @@
+export declare const GUIDANCE_SCHEMA_VERSION: 1;
+export declare const GUIDANCE_CATALOG_SCHEMA: "spexcode.guidance-catalog/v1";
+export declare const GUIDANCE_PAYLOAD_NAME: "guidance-catalog.json";
+export type GuidanceKind = 'plugin' | 'help' | 'guide';
+export type GuidanceSurface = 'system' | 'command' | 'hook' | 'skill' | 'agent' | 'review';
+export type GuidanceContentRole = 'prompt' | 'help' | 'guide' | 'signal';
+export type GuidanceSource = Readonly<{
+    path: string;
+    contentHash: string;
+    revision: string;
+}>;
+export type GuidanceEntry = Readonly<{
+    id: string;
+    kind: GuidanceKind;
+    surface?: GuidanceSurface;
+    title: string;
+    description: string;
+    contentRole: GuidanceContentRole;
+    content: string;
+    source: GuidanceSource;
+    runtime?: Readonly<{
+        path: string;
+        revision: string;
+        events: readonly string[];
+        order: number;
+        block: boolean;
+    }>;
+}>;
+export type EffectiveSystemContract = Readonly<{
+    content: string;
+    contentHash: string;
+    sourceEntryIds: readonly string[];
+}>;
+export type GuidanceBundle = Readonly<{
+    schemaVersion: typeof GUIDANCE_SCHEMA_VERSION;
+    revision: string;
+    entries: readonly GuidanceEntry[];
+    bundleHash: string;
+    catalogSchema: typeof GUIDANCE_CATALOG_SCHEMA;
+    payloadName: typeof GUIDANCE_PAYLOAD_NAME;
+    sourceRevision: string;
+    effectiveSystemContract: EffectiveSystemContract;
+}>;
+type GitReader = (args: string[]) => string;
+export type GuidanceCatalogOptions = Readonly<{
+    root?: string;
+    revision?: string;
+    sourceRevision?: (path: string) => string;
+    gitReader?: GitReader;
+}>;
+/**
+ * Immutable product-side projection over the authoritative plugin/help/guide surfaces.
+ * The constructor reads existing registries and materializes one export payload at call time.
+ */
+export declare class GuidanceCatalog {
+    readonly bundle: GuidanceBundle;
+    constructor(options?: GuidanceCatalogOptions);
+    entries(): readonly GuidanceEntry[];
+    toJSON(): GuidanceBundle;
+    exportJson(): string;
+    write(path: string): void;
+}
+export declare function buildGuidanceCatalog(options?: GuidanceCatalogOptions): GuidanceCatalog;
+export {};

package/node_modules/@spexcode/spec-cli/dist/guidance-catalog.js

@@ -0,0 +1,166 @@
+import { createHash } from 'node:crypto';
+import { writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { git, repoRoot } from '@spexcode/spec-core';
+import { loadAgentConfig, loadConfig, loadHookConfig, loadReviewConfig, loadSkillConfig, loadSystemConfig, } from '@spexcode/spec-core';
+import { helpCatalogEntries } from './help.js';
+import { guideCatalogEntries } from './guide.js';
+import { HookPromptCatalog, HOOK_PROMPT_SOURCE } from './hook-prompts.js';
+export const GUIDANCE_SCHEMA_VERSION = 1;
+export const GUIDANCE_CATALOG_SCHEMA = 'spexcode.guidance-catalog/v1';
+export const GUIDANCE_PAYLOAD_NAME = 'guidance-catalog.json';
+const SURFACES = [
+    ['agent', loadAgentConfig],
+    ['command', loadConfig],
+    ['hook', loadHookConfig],
+    ['review', loadReviewConfig],
+    ['skill', loadSkillConfig],
+    ['system', loadSystemConfig],
+];
+const sha256 = (text) => createHash('sha256').update(text, 'utf8').digest('hex');
+function freeze(value) {
+    if (!value || typeof value !== 'object' || Object.isFrozen(value))
+        return value;
+    for (const child of Object.values(value))
+        freeze(child);
+    return Object.freeze(value);
+}
+function sourcePathForPreset(preset) {
+    return join(preset.dir, 'spec.md').replaceAll('\\', '/');
+}
+function sortEntries(entries) {
+    return entries.sort((a, b) => {
+        const left = `${a.kind}\0${a.id}\0${a.surface ?? ''}\0${a.source.path}`;
+        const right = `${b.kind}\0${b.id}\0${b.surface ?? ''}\0${b.source.path}`;
+        return left < right ? -1 : left > right ? 1 : 0;
+    });
+}
+function sourceRevision(root, path, readGit) {
+    const result = readGit(['-C', root, 'log', '-1', '--format=%H', '--', path]).trim();
+    return result || 'working-tree';
+}
+function currentRevision(root, readGit) {
+    return readGit(['-C', root, 'rev-parse', 'HEAD']).trim() || 'working-tree';
+}
+function entrySource(root, path, text, revision, readSourceRevision) {
+    return { path: relative(root, join(root, path)).replaceAll('\\', '/'), contentHash: sha256(text), revision: readSourceRevision(path) || revision };
+}
+/**
+ * Immutable product-side projection over the authoritative plugin/help/guide surfaces.
+ * The constructor reads existing registries and materializes one export payload at call time.
+ */
+export class GuidanceCatalog {
+    bundle;
+    constructor(options = {}) {
+        const root = options.root ?? repoRoot();
+        const readGit = options.gitReader ?? git;
+        const revision = options.revision ?? currentRevision(root, readGit);
+        const readSourceRevision = options.sourceRevision ?? ((path) => sourceRevision(root, path, readGit));
+        const sourceRevisions = new Map();
+        const sourceRevisionFor = (path) => {
+            const known = sourceRevisions.get(path);
+            if (known)
+                return known;
+            const value = readSourceRevision(path) || revision;
+            sourceRevisions.set(path, value);
+            return value;
+        };
+        const entries = [];
+        const hookPrompts = new HookPromptCatalog();
+        for (const [surface, loader] of SURFACES) {
+            for (const preset of loader()) {
+                if (surface === 'hook') {
+                    const prompt = hookPrompts.entry(preset.name);
+                    const handler = preset.files.find((file) => file.endsWith('.sh'));
+                    if (!handler)
+                        throw new Error(`surface:hook node '${preset.name}' ships no .sh script (one co-located .sh required)`);
+                    entries.push({
+                        id: `plugin:${surface}:${preset.name}`,
+                        kind: 'plugin',
+                        surface,
+                        title: prompt.title,
+                        description: prompt.description,
+                        contentRole: prompt.role,
+                        content: prompt.content,
+                        source: entrySource(root, HOOK_PROMPT_SOURCE, prompt.content, revision, sourceRevisionFor),
+                        runtime: {
+                            path: handler,
+                            revision: sourceRevisionFor(handler),
+                            events: [...preset.events],
+                            order: preset.order,
+                            block: preset.block,
+                        },
+                    });
+                    continue;
+                }
+                const path = sourcePathForPreset(preset);
+                entries.push({
+                    id: `plugin:${surface}:${preset.name}`,
+                    kind: 'plugin',
+                    surface,
+                    title: preset.title,
+                    description: preset.desc,
+                    contentRole: 'prompt',
+                    content: preset.body,
+                    source: entrySource(root, path, preset.body, revision, sourceRevisionFor),
+                });
+            }
+        }
+        for (const entry of helpCatalogEntries()) {
+            const path = 'spec-cli/src/help.ts';
+            entries.push({
+                id: `help:${entry.id}`,
+                kind: 'help',
+                title: entry.title,
+                description: 'CLI command usage and safety guidance',
+                contentRole: 'help',
+                content: entry.text,
+                source: entrySource(root, path, entry.text, revision, sourceRevisionFor),
+            });
+        }
+        for (const entry of guideCatalogEntries()) {
+            const path = 'spec-cli/src/guide.ts';
+            entries.push({
+                id: `guide:${entry.id}`,
+                kind: 'guide',
+                title: entry.title,
+                description: 'CLI workflow and format guidance',
+                contentRole: 'guide',
+                content: entry.text,
+                source: entrySource(root, path, entry.text, revision, sourceRevisionFor),
+            });
+        }
+        const systemEntries = entries.filter((entry) => entry.kind === 'plugin' && entry.surface === 'system');
+        const effectiveSystemContent = systemEntries.map((entry) => entry.content.trim()).filter(Boolean).join('\n\n');
+        const payload = {
+            schemaVersion: GUIDANCE_SCHEMA_VERSION,
+            revision,
+            entries: sortEntries(entries),
+            catalogSchema: GUIDANCE_CATALOG_SCHEMA,
+            payloadName: GUIDANCE_PAYLOAD_NAME,
+            sourceRevision: revision,
+            effectiveSystemContract: {
+                content: effectiveSystemContent,
+                contentHash: sha256(effectiveSystemContent),
+                sourceEntryIds: systemEntries.map((entry) => entry.id),
+            },
+        };
+        const bundleHash = sha256(JSON.stringify(payload));
+        this.bundle = freeze({ ...payload, bundleHash });
+    }
+    entries() {
+        return this.bundle.entries;
+    }
+    toJSON() {
+        return this.bundle;
+    }
+    exportJson() {
+        return `${JSON.stringify(this.bundle, null, 2)}\n`;
+    }
+    write(path) {
+        writeFileSync(path, this.exportJson(), 'utf8');
+    }
+}
+export function buildGuidanceCatalog(options = {}) {
+    return new GuidanceCatalog(options);
+}

package/node_modules/@spexcode/spec-cli/dist/guide.d.ts

@@ -0,0 +1,8 @@
+export declare function guideText(topic?: string): string | null;
+export declare function guideTopics(): string[];
+export type GuideCatalogEntry = Readonly<{
+    id: string;
+    title: string;
+    text: string;
+}>;
+export declare function guideCatalogEntries(): readonly GuideCatalogEntry[];

package/{spec-cli/src/guide.ts → node_modules/@spexcode/spec-cli/dist/guide.js}

@@ -14,7 +14,7 @@ the rest, you don't hand-author the spec tree or wire the dashboard yourself.
    startup commands.)
 
 2. Adopt a repo
-     cd <your-repo> && spex init --harness claude,codex,opencode,pi,claude-headless,opencode-headless,pi-headless,codex-headless   # seeds .spec/ + git hooks (additive, never overwrites)
+     cd <your-repo> && spex init --harness claude,codex,opencode,pi,zcode,claude-headless,opencode-headless,pi-headless,codex-headless   # seeds .spec/ + git hooks (additive, never overwrites)
    --harness is required and has no default — the explicit choice of which harness(es) materialize
    delivers into. The example lists every built-in; drop the ones you don't use (any one id or
    comma-separated subset is valid).
@@ -42,8 +42,7 @@ Look these up on demand — the formats an agent authors, and the settings it co
   spex guide settings   the spexcode.json / spexcode.local.json settings (launchers, dashboard icon, upload,
                         lint budgets, layout) — every field, and which of the two files it belongs in
   spex guide footprint  the footprint model — what SpexCode plants in a repo, and who sees it
-                        (committed | ignored | hidden), and every migration recipe`
-
+                        (committed | ignored | hidden), and every migration recipe`;
 const SPEC = `spex guide spec — the spec.md file format
 
 A spec node is a DIRECTORY under .spec/<project>/…/<id>/ holding a spec.md. The node's id is its leaf dir
@@ -101,6 +100,13 @@ code does it. Two optional level-2 headings split ground truth from detail:
 Bodies without those headings are read whole. Link sibling nodes with [[node-id]] — every link must name
 a REAL node (lint's mention rule; backtick a placeholder like \`[[node]]\` so it reads as sample text).
 
+COMMENT ALTITUDE: specs own intent, invariants, policy, and observable contracts; comments only navigate
+non-obvious local decisions. Put contract or intent in the owning spec body, not a code comment. Keep a short
+nearby comment only for ordering, platform behavior, measured pitfalls, or why a plausible alternative is
+unsafe; delete commentary that merely translates code or repeats a name/type. Preserve measured values,
+version-specific behavior, and rejected alternatives not in the spec. \`@@@title - explanation\` is reserved for
+genuinely tricky surviving local reasoning.
+
 WHAT lint CHECKS (spex spec lint; the pre-commit hook gates on errors):
   integrity  (error)  every code:/related: path exists — and every anchor RESOLVES: a dead anchor (unit
                       deleted/renamed), an ambiguous one (two same-named units in one file), a file that
@@ -144,8 +150,10 @@ Heuristic spec health is deliberately outside this production gate. Bare \`spex
 altitude and breadth findings; the tidy workflow consumes that report and adds semantic judgment.
 
 LIFECYCLE: author each node on a node/<id> branch, one node per commit; \`spex spec lint\` must reach 0 errors
-before merge. \`spex init\` seeds the first tree; \`spex guide eval\` covers the sibling eval.md, the measurement file.`
+before merge. \`spex init\` seeds the first tree; \`spex guide eval\` covers the sibling eval.md, the measurement file.
 
+SHARED LANDING: if the shared checkout is mid-merge, wait. Never abort or resolve someone else's merge; if your
+own landing stops half-merged, abort it and report.`;
 const EVAL = `spex guide eval — the eval.md file format
 
 An eval.md sits BESIDE a node's spec.md and says how to MEASURE the node's loss — the gap between live
@@ -187,6 +195,13 @@ pre-commit \`internal check-staged\` BLOCKS the commit.
 BODY (after the frontmatter): prose naming the measurement method — YATU ("You As The User"): the agent
 looks at / calls the real product surface, not an internal helper chosen to make the evidence easy.
 
+REPAIR EVIDENCE: for a bug fix, use one scenario's fail→pass pair. A, BEFORE EDITING: find the violated scenario
+or add one to \`eval.md\`, run it against the old committed behavior, and file
+\`spex eval add <node> --scenario <s> --fail\` with evidence of the failure. B, AFTER EDITING: run that same
+scenario against the working tree until it passes; commit the verified tree; then file
+\`spex eval add <node> --scenario <s> --pass\`. The measurement's \`codeSha\` must be that commit. New intent has no
+prior failure to reproduce.
+
 MEASURING AND FILING: the agent runs the scenario however it likes (a browser run, an API
 transcript, a by-hand pass), compares the result to \`expected\`, and files it:
   spex eval add <node> [--scenario <name>] (--pass | --fail) [--note <text>]
@@ -227,6 +242,31 @@ PICK THE EVIDENCE KIND BY WHAT THE BEHAVIOUR DOES OVER TIME:
                       \`data\` — rendered as a validatable data block, not flattened into scrolling transcript
                       text; free-form output stays a transcript. You pick the flag; the KIND follows the bytes.
 The flags combine in ONE filing — several stills can ride beside the clip of the same run.
+POPULATION DISCIPLINE: when \`expected\` quantifies over a set ("every X is Y", "nothing under Z"), the
+measurement reports the set's SIZE, not only the verdict. An empty set satisfies a universal claim
+VACUOUSLY, so a pass over nothing and a real pass are indistinguishable — and the universal form reads
+STRICTER than an enumeration, which is what makes it the hardest wrong-population case to catch. File
+\`N of N\`, never a bare boolean: \`0 of 0\` shows itself, \`true\` does not. The denominator must come from a
+source that can DISAGREE with the numerator — count the population off the surface that does NOT decide the
+outcome (a backend export, a ledger, the enumeration upstream of the thing under test) and the passing members
+off the surface under test. A ratio whose halves share one source says only "what I selected, I selected": a
+selector that silently drops half the population reports \`3 of 3\` when the truth is 6. Two weaker defences
+that do not substitute — a precondition sentence depends on the next author remembering it, a printed
+denominator depends on a reader noticing it. Nothing here enforces either (the schema has no population
+field), so treat a zero-population run as a NON-measurement and do not file it. Cheaper than any of that, when
+you can get it: restate the claim over something the product CANNOT make empty. "every active node's name is
+readable" needs someone to arrange activity and goes vacuous when nobody does; "the rendered size never falls
+below the authored size" is a property of the viewport itself, true of a one-node graph, and has no
+population to get wrong. A claim with no population beats a well-reported one.
+RENDERED GEOMETRY (browser): measure the rendered BOX, never the authored STYLE. An ancestor CSS \`transform\`
+— the ordinary zoom/pan wrapper on a canvas or graph view — does NOT change computed style, so
+\`getComputedStyle(el).fontSize\` answers the AUTHORED size while the screen shows that size times the
+ancestor scale, and the measurement is a SILENT FALSE PASS. (No numbers here on purpose: the authored size is
+whatever this project's stylesheet says today, and a manual that hard-codes one teaches a constant that
+drifts — read it off the tree you are measuring.) Go through \`getBoundingClientRect()\` (it carries the
+ancestor scale) and derive the effective size from the box, or from a known string's width. This is also why
+a geometric claim ships WITH its \`--image\`: a rect can be computed wrong, while "is that text legible" is
+human-judgeable, so the two evidences cover each other.
 ANCHOR DISCIPLINE: an eval's \`codeSha\` is HEAD at filing time, and a git sha names only a COMMIT — an
 uncommitted change has none. So measure the tree you are about to commit, COMMIT it, then file; confidence
 is earned on the working tree, but the anchor can only land after the commit. Filing from a dirty tree
@@ -250,10 +290,8 @@ code file or the scenario (the eval.md) moves since it was filed.
                                  eval-owners (a file governed by > maxOwners scenarios — split it)
   spex eval ls <node>            the eval timeline (verdict · freshness · evidence), newest first
   spex eval scenario ls [<node>] the declared contracts; text --unmeasured = blind-spot worklist; --json = canonical declaration index
-  spex eval clean                GC the content-addressed evidence cache`
-
-const UPLOAD_DEFAULTS = uploadPolicyDefaults()
-
+  spex eval clean                GC the content-addressed evidence cache`;
+const UPLOAD_DEFAULTS = uploadPolicyDefaults();
 const SETTINGS = `spex guide settings — SpexCode's runtime settings (spexcode.json / spexcode.local.json)
 
 SpexCode reads PROJECT runtime settings from TWO optional JSON files at the repo root. There is no imperative
@@ -285,7 +323,8 @@ see LAUNCHERS.
 ── LAYOUT (spexcode.json — portable; set only for a NON-DEFAULT repo layout) ──
   main          path to the source-of-truth checkout. Default: the \`main\` worktree.
   mainBranch    the stable source-of-truth BRANCH worktrees fork from. spex init stamps the root checkout's
-                branch at adoption; an older omitted value uses the conventional main.
+                branch at adoption and the stamped value stays put for every later checkout, so a clone or a
+                fresh worktree does not re-guess it; an older omitted value uses the conventional main.
   branchPrefix  how a node branch is named. Default "node/".
 Example — a repo whose trunk is \`staging\`, not \`main\`:
   { "mainBranch": "staging" }
@@ -492,8 +531,7 @@ Example — tune opt-in health diagnosis without changing the lint gate:
               stamps the explicit choice, and a missing field fails materialize loud. PERSISTENT and
               git-transactional: the edit takes effect at the next git-native materialize anchor (the commit
               that carries it, a checkout/merge that receives it, or a manual \`spex materialize\`) — a
-              deselected harness's artifacts are pruned by that pass.`
-
+              deselected harness's artifacts are pruned by that pass.`;
 const FOOTPRINT = `spex guide footprint — what SpexCode plants in a repo, and who sees it (one fixed behavior per kind)
 
 SpexCode claims software engineering's HEAD (the recording of intent) and TAIL (the storage of
@@ -573,19 +611,74 @@ not a flag flip.
   legacy untracked spec     track the sources once:  git add .spec spexcode.json  (commit on your branch)
                             WARNING: tracking is not retroactive secrecy — history already pushed
                             elsewhere cannot be recalled.
-  back out entirely         \`spex uninstall\` (add --hooks to also remove the spexcode git hooks).`
-
-const TOPICS: Record<string, string> = { spec: SPEC, eval: EVAL, settings: SETTINGS, footprint: FOOTPRINT }
-
+  back out entirely         \`spex uninstall\` (add --hooks to also remove the spexcode git hooks).`;
+const FILES = `spex guide files — hand an agent artifact back to the human
+
+Use the session's file list when an artifact belongs in the human's hands:
+
+  spex session files add <path>      publish one current file path
+  spex session files ls              read your published paths
+  spex session files retract <path>  withdraw one path
+
+Posting resolves a relative path from your current directory and records its absolute path beside the global
+session record. It copies, moves, stages, and uploads NOTHING. The path is live: editing the file after
+posting changes what the human downloads. The reference is host-local; opening the session elsewhere cannot
+make its path point at another machine's file.
+
+The session page's top-right files icon is grey while the list is empty. Once live, it opens the posted list;
+choosing a path previews its current text or raster-image bytes in a pop-out, while the adjacent download tool
+downloads it through the backend at that moment. Previews are limited to 2 MiB, text and PNG/JPEG/GIF/WebP;
+other types and larger files say to download instead. A missing, moved, or unreadable target stays listed but
+reports that it no longer exists. The backend refuses a preview or download for any path not on that session's
+list.
+
+This is the reverse of a dashboard attachment: [[file-attach]] sends human bytes to an agent. Files publishes
+an agent-owned path for a human to download.`;
+const WEB = `spex guide web — hand a running local web service to the human
+
+Use the session web list after starting a local page the human should inspect:
+
+  spex session web add http://127.0.0.1:5173/
+  spex session web ls
+  spex session web retract http://127.0.0.1:5173/
+
+Posting records the canonical loopback HTTP URL beside the global session record. It does not fetch the page,
+start a process, or move bytes. The dashboard uses its own same-origin gateway only when the human opens the
+preview, including WebSocket traffic, so changes to the running service are visible at that moment.
+
+Only loopback HTTP URLs with an explicit port are accepted: 127.0.0.1, localhost, or ::1. The service remains
+host-local and must stay running. A stopped service remains listed and reports that its upstream is unavailable.
+The proxy has a path prefix, so use relative asset/navigation URLs or configure your dev server's base path;
+hard-coded root-absolute Vite/Next assets cannot be made portable by a proxy guessing at JavaScript.`;
+const TOPICS = { spec: SPEC, eval: EVAL, settings: SETTINGS, footprint: FOOTPRINT, files: FILES, web: WEB };
 // every guide page ends by naming the OTHER help layer, so a reader never dead-ends here: guide is
 // the skill layer (workflows · formats · settings); command usage lives in help.ts's two layers.
-const FOOTER = `\n\n(This is the skill layer. Command usage: \`spex help\` for the map, \`spex help <command>\` for one command.)`
-
+const FOOTER = `\n\n(This is the skill layer. Command usage: \`spex help\` for the map, \`spex help <command>\` for one command.)`;
 // null = unknown topic: the caller fails loud (exit non-zero) while still naming the layers to go
 // back to — an unknown topic must never read as a successful page ([[cli-surface]]'s dead-end rule).
-export function guideText(topic?: string): string | null {
-  if (!topic) return SETUP + FOOTER
-  const t = TOPICS[topic]
-  return t ? t + FOOTER : null
+export function guideText(topic) {
+    if (!topic)
+        return SETUP + FOOTER;
+    const t = TOPICS[topic];
+    return t ? t + FOOTER : null;
+}
+// @@@ the unknown-topic list is DERIVED, never re-typed - a hand-kept enumeration goes blind the moment a
+// topic is added beside it, and it did: `files` and `web` shipped while the error still named four.
+export function guideTopics() {
+    return Object.keys(TOPICS);
+}
+// The catalog indexes the same rendered pages the CLI serves. Keeping this projection beside TOPICS makes a
+// newly registered page automatically appear in the export and in the unknown-topic diagnostic.
+export function guideCatalogEntries() {
+    const entries = [];
+    const setup = guideText();
+    if (setup)
+        entries.push({ id: 'setup', title: 'spex guide', text: setup });
+    for (const topic of guideTopics()) {
+        const text = guideText(topic);
+        if (text)
+            entries.push({ id: topic, title: `spex guide ${topic}`, text });
+    }
+    return entries;
 }
-import { uploadPolicyDefaults } from './layout.js'
+import { uploadPolicyDefaults } from '@spexcode/spec-core';

package/node_modules/@spexcode/spec-cli/dist/harness-select.d.ts

@@ -0,0 +1,18 @@
+import { type Harness, type HarnessId } from './harness.js';
+export type HarnessTarget = {
+    kind: 'native';
+    id: HarnessId;
+} | {
+    kind: 'plugin';
+    folder: string;
+};
+export declare const NATIVE_HARNESS_IDS: readonly HarnessId[];
+export declare function parseHarnessFlag(spec: string): unknown[];
+export declare function resolveHarnessTargets(raw: unknown): HarnessTarget[];
+export declare function partitionHarnesses(targets: HarnessTarget[]): {
+    selected: Harness[];
+    unselected: Harness[];
+    plugins: {
+        folder: string;
+    }[];
+};

package/node_modules/@spexcode/spec-cli/dist/harness-select.js

@@ -0,0 +1,62 @@
+import { HARNESSES } from './harness.js';
+// the native vocabulary (for messages and init's flag parsing). There is NO default set: the delivery
+// targets are an explicit adopter choice, stamped by `spex init --harness` and read back from config forever.
+export const NATIVE_HARNESS_IDS = HARNESSES.map((h) => h.id);
+const KNOWN = HARNESSES.map((h) => h.id);
+// the one-line repair every missing-selection error carries — the field is REQUIRED, never defaulted,
+// because with many harnesses a silent "deliver everywhere" would litter the adopter's tree with artifacts
+// for tools they never installed.
+const MISSING = `spexcode.json has no "harnesses" field — the delivery targets are an EXPLICIT choice, never a default. Declare it, e.g. "harnesses": ["claude"] — members are native ids (${KNOWN.join(', ')}) or {"plugin":"<folder>"}. Fresh adoption: \`spex init --harness <ids>\` stamps it.`;
+// parse `spex init --harness <spec>` into the raw JSON members the `harnesses` field carries: a comma-
+// separated list where `plugin:<folder>` means a plugin target and anything else is a native id. Pure
+// spelling translation — legality (unknown ids, plugin exclusivity) stays with resolveHarnessTargets.
+export function parseHarnessFlag(spec) {
+    return spec.split(',').map((s) => s.trim()).filter(Boolean)
+        .map((s) => (s.startsWith('plugin:') ? { plugin: s.slice('plugin:'.length) } : s));
+}
+// parse + validate the spexcode.json `harnesses` field into resolved targets. FAIL LOUD on an illegal set —
+// materialize and init both gate on this so a bad config never silently delivers the wrong thing. `raw` is the
+// JSON value as written; a MISSING field is itself illegal (the choice must exist, stamped by init).
+export function resolveHarnessTargets(raw) {
+    if (raw === undefined || raw === null)
+        throw new Error(MISSING);
+    if (!Array.isArray(raw))
+        throw new Error(`spexcode.json "harnesses" must be an ARRAY of targets (got ${typeof raw}). Members are native ids (${KNOWN.join(', ')}) or {"plugin":"<folder>"}.`);
+    if (raw.length === 0)
+        throw new Error(`spexcode.json "harnesses" is EMPTY — list at least one target: native ids (${KNOWN.join(', ')}) or {"plugin":"<folder>"}.`);
+    const targets = [];
+    for (const m of raw) {
+        if (typeof m === 'string') {
+            if (m === 'plugin')
+                throw new Error(`spexcode.json "harnesses": a plugin target needs an EXPLICIT landing folder — write {"plugin":"<folder>"} (e.g. {"plugin":".adopter-a"}), not the bare string "plugin", because each host agent reads a different plugins dir.`);
+            if (!KNOWN.includes(m))
+                throw new Error(`spexcode.json "harnesses": unknown harness id "${m}" — known native ids are ${KNOWN.join(', ')}, or use {"plugin":"<folder>"}.`);
+            targets.push({ kind: 'native', id: m });
+        }
+        else if (m && typeof m === 'object' && !Array.isArray(m) && 'plugin' in m) {
+            const folder = m.plugin;
+            if (typeof folder !== 'string' || !folder.trim())
+                throw new Error(`spexcode.json "harnesses": a {"plugin":…} target needs a NON-EMPTY folder string (e.g. {"plugin":".adopter-a"}) — each host agent reads a different plugins dir, so the folder must be explicit.`);
+            targets.push({ kind: 'plugin', folder: folder.trim() });
+        }
+        else {
+            throw new Error(`spexcode.json "harnesses": each member must be a native id string (${KNOWN.join(', ')}) or a {"plugin":"<folder>"} object — got ${JSON.stringify(m)}.`);
+        }
+    }
+    // PLUGIN EXCLUSIVITY: a plugin bundle is a SUPERSET delivery to its host agent, so pairing it with any
+    // native harness double-delivers. So a set with a plugin may carry NO native harness.
+    const natives = targets.filter((t) => t.kind === 'native');
+    if (targets.some((t) => t.kind === 'plugin') && natives.length)
+        throw new Error(`spexcode.json "harnesses": a plugin target is EXCLUSIVE — it cannot coexist with native harnesses (${natives.map((t) => t.id).join(', ')}). A plugin bundle already delivers the whole system to its host agent, so pairing it with a native harness double-delivers. Choose EITHER native harnesses OR plugin target(s).`);
+    return targets;
+}
+// split the live HARNESSES adapters by whether the resolved targets SELECT them: selected get write()n,
+// unselected get clean()ed (pruned). `plugins` carries the plugin targets (no emitter yet — a later node).
+export function partitionHarnesses(targets) {
+    const selectedIds = new Set(targets.filter((t) => t.kind === 'native').map((t) => t.id));
+    return {
+        selected: HARNESSES.filter((h) => selectedIds.has(h.id)),
+        unselected: HARNESSES.filter((h) => !selectedIds.has(h.id)),
+        plugins: targets.filter((t) => t.kind === 'plugin').map((t) => ({ folder: t.folder })),
+    };
+}