@ai-substrate/engineering-harness 0.2.0-canary.45

package/harness/cli/dist/services/scaffold/templates.js

@@ -0,0 +1,178 @@
+/**
+ * Pure string builders for the scaffolded extension starters (`harness new`,
+ * plan 006). Output is byte-exact to workshop 001 §4 so it can be asserted in
+ * tests and survives `npx`/bundling (no loose template files to resolve at
+ * runtime). Authors never see this module — only the file it writes.
+ */
+/** kebab/lower verb name → a valid camelCase JS identifier for the local const. */
+export function toIdentifier(name) {
+    return name.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+}
+function splitCommand(command) {
+    const parts = command.trim().split(/\s+/);
+    return { argv0: parts[0] ?? '', rest: parts.slice(1) };
+}
+function argsLiteral(rest) {
+    return `[${rest.map((a) => `'${a}'`).join(', ')}]`;
+}
+/** Minimal TypeScript starter — an honest `unconfigured` stub (workshop §4a). */
+export function minimalTs(name) {
+    const id = toIdentifier(name);
+    return `import type { HarnessVerb } from '@ai-substrate/engineering-harness/contract';
+
+const ${id}: HarnessVerb = {
+  name: '${name}',
+  summary: 'TODO: one-line summary of what \`harness ${name}\` does.',
+  // options: [{ flags: '--example <value>', description: 'an example flag' }],
+  run(ctx) {
+    // TODO: implement this verb. Until you do, it honestly reports "not built yet".
+    return ctx.unconfigured('Implement run() in .harness/extensions/${name}/extension.ts');
+  },
+};
+
+export default ${id};
+`;
+}
+/** Wrap-a-real-command TypeScript starter (workshop §4b). */
+export function wrapTs(name, command) {
+    const id = toIdentifier(name);
+    const { argv0, rest } = splitCommand(command);
+    return `import type { HarnessVerb } from '@ai-substrate/engineering-harness/contract';
+
+const ${id}: HarnessVerb = {
+  name: '${name}',
+  summary: 'Wraps \`${command}\`.',
+  async run(ctx) {
+    const started = Date.now();
+    const r = await ctx.exec('${argv0}', ${argsLiteral(rest)});
+    const durationMs = Date.now() - started;
+    const tail = r.stdout.trimEnd().split('\\n').slice(-20).join('\\n');
+    return r.ok
+      ? ctx.ok({ command: '${command}', durationMs, stdout: tail })
+      : ctx.error('E1', \`${command} failed (exit \${r.code})\`, {
+          details: r.stderr,
+          next_action: 'Fix the failure above, then re-run \`harness ${name}\`.',
+        });
+  },
+};
+
+export default ${id};
+`;
+}
+/** Minimal plain-JS starter — JSDoc contract reference, no runtime import (workshop §4c). */
+export function minimalJs(name) {
+    const id = toIdentifier(name);
+    return `/** @type {import('@ai-substrate/engineering-harness/contract').HarnessVerb} */
+const ${id} = {
+  name: '${name}',
+  summary: 'TODO: one-line summary of what \`harness ${name}\` does.',
+  run(ctx) {
+    // TODO: implement this verb.
+    return ctx.unconfigured('Implement run() in .harness/extensions/${name}/extension.js');
+  },
+};
+
+export default ${id};
+`;
+}
+/** Wrap-a-real-command plain-JS starter (workshop §4d). */
+export function wrapJs(name, command) {
+    const id = toIdentifier(name);
+    const { argv0, rest } = splitCommand(command);
+    return `/** @type {import('@ai-substrate/engineering-harness/contract').HarnessVerb} */
+const ${id} = {
+  name: '${name}',
+  summary: 'Wraps \`${command}\`.',
+  async run(ctx) {
+    const started = Date.now();
+    const r = await ctx.exec('${argv0}', ${argsLiteral(rest)});
+    const durationMs = Date.now() - started;
+    const tail = r.stdout.trimEnd().split('\\n').slice(-20).join('\\n');
+    return r.ok
+      ? ctx.ok({ command: '${command}', durationMs, stdout: tail })
+      : ctx.error('E1', \`${command} failed (exit \${r.code})\`, {
+          details: r.stderr,
+          next_action: 'Fix the failure above, then re-run \`harness ${name}\`.',
+        });
+  },
+};
+
+export default ${id};
+`;
+}
+/**
+ * Record-type extension starter (`harness new <name> --record`). Exports a
+ * {@link HarnessRecordType} the loader discovers by its `kind:'record'`. The
+ * record's "schema" lives in the `template` body (frontmatter + comments); the
+ * CLI is schema-agnostic, so editing the template is all it takes to design a type.
+ */
+export function recordTs(name) {
+    const id = toIdentifier(name);
+    return `import type { HarnessRecordType } from '@ai-substrate/engineering-harness/contract';
+
+const ${id}: HarnessRecordType = {
+  kind: 'record',
+  type: '${name}',
+  description: 'TODO: one-line description of the ${name} record type.',
+  // The record's schema lives HERE — frontmatter keys + commented guidance.
+  template: \`---
+record_type: ${name}
+captured_at: "<ISO8601Z>"
+# TODO: add the fields this record captures.
+---
+
+# ${name} — <subject>
+
+<!-- TODO: optional narrative; the frontmatter above is the durable signal. -->
+\`,
+};
+
+export default ${id};
+`;
+}
+/**
+ * Starter `instructions.md` for a scaffolded extension package (plan 014 AC-8).
+ * A guided TODO addressed to the CALLING agent: what the verb computes
+ * deterministically, and what judgment it expects back. Served verbatim by
+ * `harness instructions <name>` once authored.
+ */
+export function starterInstructions(name) {
+    return `# \`harness ${name}\` — agent briefing
+
+<!-- TODO: author this briefing for the CALLING agent (not a human README).
+     \`harness instructions ${name}\` serves this file verbatim, freshly read
+     on every invocation — edit it any time, no rebuild. -->
+
+## What this verb computes (the deterministic part)
+
+TODO: state exactly what \`harness ${name}\` runs or collects, and what its
+envelope \`data\` contains.
+
+## Your role (the inference part)
+
+TODO: state the judgment the calling agent is expected to apply to the output —
+what to review, what to compare against, what verdict to reach.
+
+## Watch out for
+
+TODO: list failure modes or misleading outputs an agent should not take at
+face value.
+`;
+}
+/** Pick the starter + extension from the `harness new` flags. */
+export function renderStarter(opts) {
+    const { name, js, wrap, record } = opts;
+    if (record) {
+        // Record types are TS stubs (they import the record contract); --wrap/--js don't apply.
+        return { contents: recordTs(name), variant: 'record-ts', ext: 'ts' };
+    }
+    if (wrap !== undefined) {
+        return js
+            ? { contents: wrapJs(name, wrap), variant: 'wrap-js', ext: 'js' }
+            : { contents: wrapTs(name, wrap), variant: 'wrap-ts', ext: 'ts' };
+    }
+    return js
+        ? { contents: minimalJs(name), variant: 'minimal-js', ext: 'js' }
+        : { contents: minimalTs(name), variant: 'minimal-ts', ext: 'ts' };
+}
+//# sourceMappingURL=templates.js.map

package/harness/cli/dist/services/scaffold/templates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../../src/services/scaffold/templates.ts"],"names":[],"mappings":"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"}

package/harness/cli/dist/services/shared/posix-path.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Logical paths are POSIX on every OS (plan 017).
+ *
+ * Every path the CLI *surfaces or compares* — envelope `data.path`, record
+ * messages, extension `entryPath`/`folder`, doctor hints, dedupe keys — is a
+ * LOGICAL path: forward slashes only, `.harness/...` shapes literal, identical
+ * on Windows and POSIX hosts. Physical I/O (NodeFs) keeps native separators;
+ * conversion happens ONCE at the boundary (`toPosix(proc.cwd())`,
+ * `toPosix(entryPath)`), after which everything stays in POSIX space.
+ *
+ * Allowed surface (all lexical): `toPosix`, `posixNormalize`, `posixJoin`,
+ * `posixDirname`, `posixRelative`, `isWithin`, `dedupeKey`.
+ *
+ * FORBIDDEN: `posix.resolve` (and native `resolve`) on logical paths. A
+ * drive-letter path (`C:/repo`) does not start with `/`, so `posix.resolve`
+ * treats it as RELATIVE and prepends the host cwd — silently corrupting the
+ * path. Everything here is built on `posix.normalize`/`posix.join` instead.
+ *
+ * UNC guard: Node's `posix.normalize` collapses a leading `//`
+ * (`//server/share` → `/server/share`), so every normalize-based op reattaches
+ * the second slash when the input was UNC-rooted.
+ */
+/** Module-level platform constant — the DEFAULT for case-folding, never probed in tests (P3: pass the parameter explicitly instead of patching `process.platform`). */
+export declare const IS_WIN32: boolean;
+/**
+ * Convert a possibly-Windows-shaped path to its logical POSIX form:
+ * backslashes → `/`, drive letter upper-cased (`c:` → `C:`), UNC
+ * `\\server\share` → `//server/share`. POSIX inputs pass through unchanged.
+ */
+export declare function toPosix(path: string): string;
+/** Lexical normalize in POSIX space (UNC-guarded). Accepts Windows-shaped input. */
+export declare function posixNormalize(path: string): string;
+/** Join in POSIX space (UNC-guarded). Each segment is converted via `toPosix` on the way in. */
+export declare function posixJoin(...parts: string[]): string;
+/** Dirname in POSIX space (UNC-guarded). Accepts Windows-shaped input. */
+export declare function posixDirname(path: string): string;
+/**
+ * Relative in POSIX space. Drive-letter inputs are safe: when both sides are
+ * resolved against the same host cwd the shared prefix cancels, so the result
+ * is the lexical relative between the two logical paths.
+ */
+export declare function posixRelative(from: string, to: string): string;
+/**
+ * True when `candidate` is `dir` or a descendant of it — the `../`-escape
+ * guard, computed entirely in POSIX space (literal `'../'`, never `sep`).
+ */
+export declare function isWithin(dir: string, candidate: string): boolean;
+/**
+ * Stable identity key for dedupe maps: POSIX-normalized, optionally
+ * case-folded. Case sensitivity is an EXPLICIT parameter so tests exercise
+ * both branches deterministically on any host; the default follows the
+ * platform (Windows filesystems are case-insensitive).
+ */
+export declare function dedupeKey(path: string, caseInsensitive?: boolean): string;

package/harness/cli/dist/services/shared/posix-path.js

@@ -0,0 +1,94 @@
+import { posix } from 'node:path';
+/**
+ * Logical paths are POSIX on every OS (plan 017).
+ *
+ * Every path the CLI *surfaces or compares* — envelope `data.path`, record
+ * messages, extension `entryPath`/`folder`, doctor hints, dedupe keys — is a
+ * LOGICAL path: forward slashes only, `.harness/...` shapes literal, identical
+ * on Windows and POSIX hosts. Physical I/O (NodeFs) keeps native separators;
+ * conversion happens ONCE at the boundary (`toPosix(proc.cwd())`,
+ * `toPosix(entryPath)`), after which everything stays in POSIX space.
+ *
+ * Allowed surface (all lexical): `toPosix`, `posixNormalize`, `posixJoin`,
+ * `posixDirname`, `posixRelative`, `isWithin`, `dedupeKey`.
+ *
+ * FORBIDDEN: `posix.resolve` (and native `resolve`) on logical paths. A
+ * drive-letter path (`C:/repo`) does not start with `/`, so `posix.resolve`
+ * treats it as RELATIVE and prepends the host cwd — silently corrupting the
+ * path. Everything here is built on `posix.normalize`/`posix.join` instead.
+ *
+ * UNC guard: Node's `posix.normalize` collapses a leading `//`
+ * (`//server/share` → `/server/share`), so every normalize-based op reattaches
+ * the second slash when the input was UNC-rooted.
+ */
+/** Module-level platform constant — the DEFAULT for case-folding, never probed in tests (P3: pass the parameter explicitly instead of patching `process.platform`). */
+export const IS_WIN32 = process.platform === 'win32';
+/** True when the (already forward-slashed) path is UNC-rooted: exactly `//` then a name. */
+const UNC_ROOT = /^\/\/[^/]/;
+/** Reattach the UNC root a normalize-style op collapsed (`/server/…` → `//server/…`). */
+function reattachUncRoot(original, result) {
+    if (UNC_ROOT.test(original) && !result.startsWith('//')) {
+        return `/${result}`;
+    }
+    return result;
+}
+/**
+ * Convert a possibly-Windows-shaped path to its logical POSIX form:
+ * backslashes → `/`, drive letter upper-cased (`c:` → `C:`), UNC
+ * `\\server\share` → `//server/share`. POSIX inputs pass through unchanged.
+ */
+export function toPosix(path) {
+    const slashed = path.replace(/\\/g, '/');
+    return slashed.replace(/^([a-z]):/, (_, drive) => `${drive.toUpperCase()}:`);
+}
+/** Lexical normalize in POSIX space (UNC-guarded). Accepts Windows-shaped input. */
+export function posixNormalize(path) {
+    const p = toPosix(path);
+    return reattachUncRoot(p, posix.normalize(p));
+}
+/** Join in POSIX space (UNC-guarded). Each segment is converted via `toPosix` on the way in. */
+export function posixJoin(...parts) {
+    const posixParts = parts.map(toPosix);
+    const joined = posix.join(...posixParts);
+    return reattachUncRoot(posixParts[0] ?? '', joined);
+}
+/** Dirname in POSIX space (UNC-guarded). Accepts Windows-shaped input. */
+export function posixDirname(path) {
+    const p = toPosix(path);
+    return reattachUncRoot(p, posix.dirname(p));
+}
+/**
+ * Relative in POSIX space. Drive-letter inputs are safe: when both sides are
+ * resolved against the same host cwd the shared prefix cancels, so the result
+ * is the lexical relative between the two logical paths.
+ */
+export function posixRelative(from, to) {
+    return posix.relative(toPosix(from), toPosix(to));
+}
+/**
+ * True when `candidate` is `dir` or a descendant of it — the `../`-escape
+ * guard, computed entirely in POSIX space (literal `'../'`, never `sep`).
+ */
+export function isWithin(dir, candidate) {
+    const d = posixNormalize(dir);
+    const c = posixNormalize(candidate);
+    // Root kinds must match: a UNC tree (`//server/…`) never contains a
+    // single-slash path (or vice versa). Without this, Node's relative()
+    // collapses the doubled slash and conflates the two roots (companion F001).
+    if (UNC_ROOT.test(d) !== UNC_ROOT.test(c)) {
+        return false;
+    }
+    const rel = posixRelative(d, c);
+    return rel === '' || (!rel.startsWith('../') && rel !== '..' && !posix.isAbsolute(rel));
+}
+/**
+ * Stable identity key for dedupe maps: POSIX-normalized, optionally
+ * case-folded. Case sensitivity is an EXPLICIT parameter so tests exercise
+ * both branches deterministically on any host; the default follows the
+ * platform (Windows filesystems are case-insensitive).
+ */
+export function dedupeKey(path, caseInsensitive = IS_WIN32) {
+    const key = posixNormalize(path);
+    return caseInsensitive ? key.toLowerCase() : key;
+}
+//# sourceMappingURL=posix-path.js.map

package/harness/cli/dist/services/shared/posix-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"posix-path.js","sourceRoot":"","sources":["../../../src/services/shared/posix-path.ts"],"names":[],"mappings":"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"}

package/harness/cli/dist/services/shared/temp.d.ts

@@ -0,0 +1,24 @@
+import type { FsPort } from '../../adapters/fs/fs-port.js';
+import type { ProcessPort } from '../../adapters/process/process-port.js';
+/**
+ * Shared transient-storage mechanics for `.harness/temp/` — the gitignored,
+ * never-committed scratch class that sits beside the committed
+ * `.harness/records/`. Relocated from record-service (plan 015 D1) so the
+ * `record` and `observe` services share the guarantee without either importing
+ * the other's internals.
+ */
+export declare const HARNESS_DIR = ".harness";
+export declare const TEMP_DIR = "temp";
+export declare const TEMP_GITIGNORE = "# Crash-resilient agent scratch \u2014 never committed.\n*\n";
+/** The ports the temp guarantee needs (a structural subset of RecordDeps/ObserveDeps). */
+export interface TempDeps {
+    fs: FsPort;
+    proc: ProcessPort;
+}
+/**
+ * Ensure `.harness/temp/` exists and is self-gitignored on first use: the
+ * crash-resilient scratch buffer is never committed even in a consumer repo
+ * that hasn't added the root `.gitignore` rule. Idempotent — only writes what's
+ * missing. Returns the absolute temp dir.
+ */
+export declare function ensureTemp(deps: TempDeps): string;

package/harness/cli/dist/services/shared/temp.js

@@ -0,0 +1,29 @@
+import { posixJoin, toPosix } from './posix-path.js';
+/**
+ * Shared transient-storage mechanics for `.harness/temp/` — the gitignored,
+ * never-committed scratch class that sits beside the committed
+ * `.harness/records/`. Relocated from record-service (plan 015 D1) so the
+ * `record` and `observe` services share the guarantee without either importing
+ * the other's internals.
+ */
+export const HARNESS_DIR = '.harness';
+export const TEMP_DIR = 'temp';
+export const TEMP_GITIGNORE = '# Crash-resilient agent scratch — never committed.\n*\n';
+/**
+ * Ensure `.harness/temp/` exists and is self-gitignored on first use: the
+ * crash-resilient scratch buffer is never committed even in a consumer repo
+ * that hasn't added the root `.gitignore` rule. Idempotent — only writes what's
+ * missing. Returns the absolute temp dir.
+ */
+export function ensureTemp(deps) {
+    const tempDir = posixJoin(toPosix(deps.proc.cwd()), HARNESS_DIR, TEMP_DIR);
+    if (!deps.fs.exists(tempDir)) {
+        deps.fs.mkdirp(tempDir);
+    }
+    const gitignore = posixJoin(tempDir, '.gitignore');
+    if (!deps.fs.exists(gitignore)) {
+        deps.fs.writeText(gitignore, TEMP_GITIGNORE);
+    }
+    return tempDir;
+}
+//# sourceMappingURL=temp.js.map

package/harness/cli/dist/services/shared/temp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"temp.js","sourceRoot":"","sources":["../../../src/services/shared/temp.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAErD;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG,UAAU,CAAC;AACtC,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC;AAE/B,MAAM,CAAC,MAAM,cAAc,GAAG,yDAAyD,CAAC;AAQxF;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,IAAc;IACvC,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC;IAC3E,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7B,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC1B,CAAC;IACD,MAAM,SAAS,GAAG,SAAS,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IACnD,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC;QAC/B,IAAI,CAAC,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/harness/cli/dist/services/skills/contract.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Contract for `harness skills install` — the options the act collects and the
+ * pure service turns into an `npx skills` argv. Kept tiny + I/O-free so the argv
+ * construction is unit-testable (Principle 3: pure logic, no child spawn here).
+ */
+/**
+ * The default skills source: this repo's `skills/` subtree (the `owner/repo/subdir`
+ * form `npx skills add` accepts), so the command installs THIS harness's skills from
+ * anywhere it runs. Scoped to `/skills` ON PURPOSE: a bare `owner/repo` makes the
+ * installer fetch the whole repo and recursively sweep EVERY `SKILL.md` it finds —
+ * which would pull in any stray skill under `agents/`, fixtures, or future top-level
+ * dirs. Pinning the subdir keeps the install to the published skill set only.
+ */
+export declare const DEFAULT_SKILLS_SOURCE = "AI-Substrate/harness-engineering/skills";
+/** CLI targets the Vercel `skills` tool understands (the `-a <agent>` values). Surfaced for help/validation. */
+export declare const KNOWN_SKILL_TARGETS: readonly ["claude-code", "codex", "cursor", "github-copilot", "opencode", "pi"];
+/**
+ * Slugs this harness PUBLISHED in the past and has since RENAMED or REMOVED. The
+ * Vercel `npx skills` installer has no native prune — `add` and `update` are both
+ * additive (verified empirically), so a renamed skill's OLD copy lingers on disk
+ * (and keeps loading) forever. `harness skills update` removes these AFTER the
+ * refresh, so a rename never leaves a stale twin behind — the exact failure this
+ * fixes is `harnessability-assessment` AND its new name
+ * `eng-harness-0-harnessability-assessment` both installed at once.
+ *
+ * MAINTENANCE CONTRACT: when you RENAME or REMOVE a published skill (any dir under
+ * `skills/`), add its OLD slug here IN THE SAME CHANGE. `npx skills remove` no-ops
+ * (exit 0) on a slug that isn't installed, so over-listing is harmless; the only
+ * cost of forgetting is that the old copy lingers for consumers. Keep every entry
+ * HARNESS-NAMESPACED (`harness-*` / `eng-harness-*` / `engineering-harness-*` /
+ * `harnessability-*`) so a third-party skill that happens to share a generic name
+ * is never pruned out from under a user.
+ */
+export declare const LEGACY_SKILL_SLUGS: readonly ["harness-0-setup", "harness-1-boot", "harness-2-backpressure", "harness-3-observe", "harness-4-retro", "eng-harness-0-setup", "eng-harness-3-observe", "engineering-harness-orient", "engineering-harness-setup", "harnessability-assessment"];
+export interface SkillsInstallOptions {
+    /** `owner/repo` (or `owner/repo/subdir`, or a local path) passed to `npx skills add`. */
+    source: string;
+    /** One or more CLI targets → fanned out as repeated `-a <target>`. Must be non-empty. */
+    targets: string[];
+    /** Global install (`-g`) vs project-local (omit `-g`). */
+    global: boolean;
+    /** Optional single-skill filters → repeated `-s <slug>`. */
+    skills?: string[];
+}
+export interface SkillsRemoveOptions {
+    /** Skill slugs to remove → POSITIONAL args to `npx skills remove`. Must be non-empty. */
+    slugs: string[];
+    /** One or more CLI targets → fanned out as repeated `-a <target>`. Must be non-empty. */
+    targets: string[];
+    /** Remove from the global install (`-g`) vs project-local (omit `-g`). */
+    global: boolean;
+}

package/harness/cli/dist/services/skills/contract.js

@@ -0,0 +1,55 @@
+/**
+ * Contract for `harness skills install` — the options the act collects and the
+ * pure service turns into an `npx skills` argv. Kept tiny + I/O-free so the argv
+ * construction is unit-testable (Principle 3: pure logic, no child spawn here).
+ */
+/**
+ * The default skills source: this repo's `skills/` subtree (the `owner/repo/subdir`
+ * form `npx skills add` accepts), so the command installs THIS harness's skills from
+ * anywhere it runs. Scoped to `/skills` ON PURPOSE: a bare `owner/repo` makes the
+ * installer fetch the whole repo and recursively sweep EVERY `SKILL.md` it finds —
+ * which would pull in any stray skill under `agents/`, fixtures, or future top-level
+ * dirs. Pinning the subdir keeps the install to the published skill set only.
+ */
+export const DEFAULT_SKILLS_SOURCE = 'AI-Substrate/harness-engineering/skills';
+/** CLI targets the Vercel `skills` tool understands (the `-a <agent>` values). Surfaced for help/validation. */
+export const KNOWN_SKILL_TARGETS = [
+    'claude-code',
+    'codex',
+    'cursor',
+    'github-copilot',
+    'opencode',
+    'pi',
+];
+/**
+ * Slugs this harness PUBLISHED in the past and has since RENAMED or REMOVED. The
+ * Vercel `npx skills` installer has no native prune — `add` and `update` are both
+ * additive (verified empirically), so a renamed skill's OLD copy lingers on disk
+ * (and keeps loading) forever. `harness skills update` removes these AFTER the
+ * refresh, so a rename never leaves a stale twin behind — the exact failure this
+ * fixes is `harnessability-assessment` AND its new name
+ * `eng-harness-0-harnessability-assessment` both installed at once.
+ *
+ * MAINTENANCE CONTRACT: when you RENAME or REMOVE a published skill (any dir under
+ * `skills/`), add its OLD slug here IN THE SAME CHANGE. `npx skills remove` no-ops
+ * (exit 0) on a slug that isn't installed, so over-listing is harmless; the only
+ * cost of forgetting is that the old copy lingers for consumers. Keep every entry
+ * HARNESS-NAMESPACED (`harness-*` / `eng-harness-*` / `engineering-harness-*` /
+ * `harnessability-*`) so a third-party skill that happens to share a generic name
+ * is never pruned out from under a user.
+ */
+export const LEGACY_SKILL_SLUGS = [
+    // Pre-`eng-` loop family → renamed to eng-harness-1-boot … eng-harness-4-retro.
+    'harness-0-setup',
+    'harness-1-boot',
+    'harness-2-backpressure',
+    'harness-3-observe',
+    'harness-4-retro',
+    // Setup-group slugs since renamed/removed.
+    'eng-harness-0-setup', // → eng-harness-0-adopt
+    'eng-harness-3-observe', // observe folded into eng-harness-4-retro
+    'engineering-harness-orient', // → harnessability-assessment → eng-harness-0-harnessability-assessment
+    'engineering-harness-setup', // → eng-harness-0-setup → eng-harness-0-adopt
+    'harnessability-assessment', // → eng-harness-0-harnessability-assessment
+];
+//# sourceMappingURL=contract.js.map

package/harness/cli/dist/services/skills/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../../src/services/skills/contract.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,yCAAyC,CAAC;AAE/E,gHAAgH;AAChH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,aAAa;IACb,OAAO;IACP,QAAQ;IACR,gBAAgB;IAChB,UAAU;IACV,IAAI;CACI,CAAC;AAEX;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,gFAAgF;IAChF,iBAAiB;IACjB,gBAAgB;IAChB,wBAAwB;IACxB,mBAAmB;IACnB,iBAAiB;IACjB,2CAA2C;IAC3C,qBAAqB,EAAE,wBAAwB;IAC/C,uBAAuB,EAAE,0CAA0C;IACnE,4BAA4B,EAAE,wEAAwE;IACtG,2BAA2B,EAAE,8CAA8C;IAC3E,2BAA2B,EAAE,4CAA4C;CACjE,CAAC"}

package/harness/cli/dist/services/skills/skills-service.d.ts

@@ -0,0 +1,73 @@
+import type { SkillsInstallOptions, SkillsRemoveOptions } from './contract.js';
+/**
+ * Outcome of resolving a `--source` (+ optional branch) into a specifier `npx
+ * skills add` actually understands. Discriminated so the act can map a bad
+ * combination onto an `E108` envelope without the pure layer doing any I/O.
+ */
+export type SkillsSourceResolution = {
+    ok: true;
+    source: string;
+    branch?: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Translate a friendly `--source` (+ optional `--branch`, or a `#ref` suffix on
+ * the source) into the specifier the Vercel installer truly accepts.
+ *
+ * Why this exists: `npx skills add` has NO `--branch`/`--ref` flag and NO
+ * `owner/repo#ref` shorthand (vercel-labs/skills#42 is an open request for it).
+ * Its ONLY documented branch mechanism is a GitHub *tree URL*:
+ * `https://github.com/<owner>/<repo>/tree/<ref>[/<subdir>]`. So when the user
+ * names a branch, we rewrite the GitHub shorthand into that URL form.
+ *
+ * Invariants:
+ *   - **No ref → verbatim pass-through.** The source is returned unchanged (the
+ *     default `owner/repo` shorthand installs the default branch, exactly as
+ *     before this flag existed) — so every existing call site is untouched.
+ *   - **Ref precedence**: an explicit `branch` arg wins over a `#ref` suffix.
+ *   - **Slashed refs are rejected** (`ok:false`). The installer reads the first
+ *     path segment after `/tree/` as the *entire* ref, so `feat/x` would silently
+ *     mis-resolve to branch `feat` + subdir `x`. Failing fast (deterministic
+ *     backpressure) beats handing the installer a URL it will mis-parse.
+ *   - **Branch only applies to GitHub sources** (`owner/repo[/subdir]` or
+ *     `https://github.com/owner/repo`). A branch against a local path / GitLab /
+ *     generic git URL is rejected with guidance rather than ignored.
+ */
+export declare function resolveSkillsSource(rawSource: string, branch?: string): SkillsSourceResolution;
+/**
+ * Pure `npx skills add …` argv builder — the one place the Vercel `skills` flag
+ * surface is encoded (Principle 8: wrap, don't rebuild). No I/O, no child spawn:
+ * the act feeds the returned argv to the injected `ExecPort`, and tests assert
+ * the exact array (Principle 3). The returned array is the args AFTER `npx`, i.e.
+ * `['skills@latest', 'add', <source>, '-a', <t>, …, '-g'?, '-s', <slug>, …, '-y']`.
+ *
+ * Invariants (AC3/AC4):
+ *   - always pins `skills@latest` and always appends `-y` (UNCONDITIONALLY — the
+ *     builder makes it impossible to construct a blocking invocation, so the
+ *     interactive picker never appears regardless of caller input);
+ *   - each target fans out as a repeated `-a <target>`;
+ *   - `-g` is present iff `global` is true.
+ *
+ * Precondition: `targets` is non-empty — enforced by the act (missing `--target`
+ * → `E108`) before this is ever called.
+ */
+export declare function buildInstallArgv(opts: SkillsInstallOptions): string[];
+/**
+ * Pure `npx skills remove …` argv builder — the PRUNE half of `harness skills
+ * update` (Principle 8: wrap, don't rebuild). No I/O. Renamed/removed skills are
+ * passed as POSITIONAL slugs; `npx skills remove` no-ops (exit 0) on any slug that
+ * isn't installed, so it is safe to call with the full legacy list every time.
+ * Like the install builder it fans out `-a <target>`, adds `-g` iff global, and
+ * always appends `-y` (never blocks). Returns the args AFTER `npx`:
+ * `['skills@latest', 'remove', <slug>, …, '-a', <t>, …, '-g'?, '-y']`.
+ *
+ * Precondition: `slugs` and `targets` are both non-empty — enforced by the act.
+ */
+export declare function buildRemoveArgv(opts: SkillsRemoveOptions): string[];
+/**
+ * The human-readable command line we announce before running (and echo in the JSON
+ * envelope). Generic over any `npx skills …` argv — used for both `add` and `remove`.
+ */
+export declare function formatInstallCommand(argv: string[]): string;