wicked-crew-api-types 0.33.0 → 0.34.0

package/index.d.ts

@@ -1785,6 +1785,40 @@ export interface SkillBaselineRecord {
   venv: SkillVenvState;
 }
 
+/**
+ * Why a skill's text cannot be followed on a non-Claude CLI (F-079, api-types 0.34.0; design W4
+ * §5.1 — the same tokens wicked-garden's own lint reports):
+ *
+ *   - `plugin-root` — the text contains `${CLAUDE_PLUGIN_ROOT}` (only Claude Code substitutes it);
+ *   - `skill-dir-var` — the text contains `${CLAUDE_SKILL_DIR}` (likewise Claude-only);
+ *   - `cwd-script` — an interpreter invokes a plugin script by a path relative to the worktree cwd
+ *     (`python3 scripts/domain/extract_loop.py`) instead of the `wicked-garden run …` launcher;
+ *   - `relative-link` — a `../` link whose target exists in the bundle (the flat `<name>/SKILL.md`
+ *     layout of every non-Claude install cannot follow it);
+ *   - `cross-skill-path` — a path (plugin-root or `../`) that lands in ANOTHER skill's directory;
+ *     the portable form names that skill (`wicked-garden-<x>`) instead;
+ *   - `requires-harness:claude` — the author declared `metadata.requires-harness: claude` in the
+ *     frontmatter: the skill genuinely needs the Claude harness (not an authoring defect).
+ */
+export type SkillPortabilityReason =
+  | 'plugin-root'
+  | 'skill-dir-var'
+  | 'cwd-script'
+  | 'relative-link'
+  | 'cross-skill-path'
+  | 'requires-harness:claude';
+
+/** Per-reason portability of a skill (F-079, api-types 0.34.0) — reported beside `portable`. */
+export interface SkillPortability {
+  /** The same value as `SkillEntry.portable`: `reasons.length === 0`. */
+  portable: boolean;
+  /** Sorted, unique. Empty when portable. */
+  reasons: SkillPortabilityReason[];
+  /** Up to five anchors, `<plugin-relative file>:<line>`, one per hit in file order — where the
+   *  offending text sits (the drawer's "why" and the operator's path to the line). */
+  evidence?: string[];
+}
+
 export interface SkillEntry {
   /** Plugin-relative directory, nested layout preserved (`skills/engineering/frontend`). Never
    *  renamed — sibling `../` links depend on it. */
@@ -1794,11 +1828,17 @@ export interface SkillEntry {
    *  daemon knows (core drop-ins, crew-generated, user-registered) or a skill one of those names in
    *  its SKILL.md (repo-learn → search, mem). Disabling or renaming it is blocking. */
   core: boolean;
-  /** `false` when the skill's files resolve `${CLAUDE_PLUGIN_ROOT}`, invoke a script relative to
-   *  the cwd (`python3 -u scripts/x.py`, `./scripts/x`, …), or link `../` — Claude-only by nature:
-   *  excluded from the snapshot's `views/copilot/` and from the per-launch skill lists core builds
-   *  for the other CLIs. `portable` is the admission key for every non-Claude view (design v3.2). */
+  /** `false` when the skill's files carry any `SkillPortabilityReason` — Claude-only: excluded from
+   *  the snapshot's `views/copilot/` and from the per-launch skill lists core builds for the other
+   *  CLIs. `portable` is the admission key for every non-Claude view (design v3.2); the reasons
+   *  are reported per token in `portability` (api-types 0.34.0). wicked-garden ≥ 12.33 authors
+   *  every skill portably, so a non-portable row there is either an older garden or a skill that
+   *  declares `requires-harness: claude`. */
   portable: boolean;
+  /** Per-reason portability (F-079, api-types 0.34.0): `portable` again, the sorted unique
+   *  `reasons`, and up to five `file:line` anchors. Absent on manifests written by a daemon older
+   *  than 0.7.30 — treat absence as "reasons unknown". */
+  portability?: SkillPortability;
   /** Manifest state, orthogonal to content: a disabled skill's files stay in `effective/` and are
    *  excluded from the next published snapshot. Reset never flips it. */
   enabled: boolean;
@@ -1917,6 +1957,9 @@ export type SkillFindingKind =
   | 'core-rename'
   | 'core-missing'
   | 'support-file-edit'
+  /** A write made (or would make) the skill non-portable — a WARNING, one finding PER REASON per
+   *  file (api-types 0.34.0), anchored `file:line` at the first hit and carrying the token in
+   *  `portabilityReason`. The skill leaves every non-Claude delivery view. */
   | 'non-portable'
   /** A `${CLAUDE_PLUGIN_ROOT}/<p>` or `../<p>` reference in an enabled skill's files that does not
    *  resolve inside the would-be snapshot. Severity follows the TARGET (design v3.4 §1): a reference
@@ -2002,6 +2045,9 @@ export interface SkillConflictFinding {
   evidence: string;
   /** Why it matters. */
   explanation: string;
+  /** On a `non-portable` finding: WHICH reason this finding reports (one finding per reason per
+   *  file). Absent on every other kind (api-types 0.34.0). */
+  portabilityReason?: SkillPortabilityReason;
 }
 
 /** `POST /skills/analyze` 200 body (a PURE dry run of the publish validation: nothing persisted,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "wicked-crew-api-types",
-  "version": "0.33.0",
-  "description": "The wire contract of the wicked-crew daemon's /api/v1 REST surface and /ws CoreEvent frames \u2014 types only, zero runtime",
+  "version": "0.34.0",
+  "description": "The wire contract of the wicked-crew daemon's /api/v1 REST surface and /ws CoreEvent frames — types only, zero runtime",
   "type": "module",
   "types": "./index.d.ts",
   "exports": {