@sabaiway/agent-workflow-kit 1.2.0 → 1.4.0

package/tools/manifest/fixtures/missing-source/capability.json

@@ -0,0 +1,11 @@
+{
+  "family": "agent-workflow",
+  "schema": 1,
+  "name": "missing-source",
+  "kind": "execution-backend",
+  "version": "1.0.0",
+  "provides": ["review"],
+  "roles": {
+    "review": { "cmd": "ghost-review", "source": "bin/does-not-exist.sh" }
+  }
+}

package/tools/manifest/fixtures/nested-version-decoy/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: nested-version-decoy
+metadata:
+  version: '1.0.0'
+  nested:
+    version: '9.9.9'
+---
+
+# nested-version-decoy fixture — the DIRECT metadata.version (1.0.0) wins; the deeper
+# metadata.nested.version (9.9.9) must be ignored. capability.json declares 1.0.0 → VALID.

package/tools/manifest/fixtures/nested-version-decoy/capability.json

@@ -0,0 +1,9 @@
+{
+  "family": "agent-workflow",
+  "schema": 1,
+  "name": "nested-version-decoy",
+  "kind": "memory-substrate",
+  "version": "1.0.0",
+  "provides": [],
+  "roles": {}
+}

package/tools/manifest/fixtures/null-root/capability.json

@@ -0,0 +1 @@
+null

package/tools/manifest/fixtures/provides-roles-mismatch/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: mismatch
+metadata:
+  version: '1.0.0'
+---
+
+# mismatch fixture — `roles.review` is not listed in `provides`.

package/tools/manifest/fixtures/provides-roles-mismatch/bin/run.sh

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+exit 0

package/tools/manifest/fixtures/provides-roles-mismatch/capability.json

@@ -0,0 +1,11 @@
+{
+  "family": "agent-workflow",
+  "schema": 1,
+  "name": "mismatch",
+  "kind": "execution-backend",
+  "version": "1.0.0",
+  "provides": ["execute"],
+  "roles": {
+    "review": { "cmd": "mismatch-review", "source": "bin/run.sh" }
+  }
+}

package/tools/manifest/fixtures/stub/capability.json

@@ -0,0 +1,10 @@
+{
+  "family": "agent-workflow",
+  "schema": 1,
+  "name": "fixture-engine-stub",
+  "kind": "methodology-engine",
+  "version": "0.0.0",
+  "available": false,
+  "provides": ["plan"],
+  "roles": {}
+}

package/tools/manifest/fixtures/traversal-source/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: traversal-source
+metadata:
+  version: '1.0.0'
+---
+
+# traversal-source fixture — a `..` traversal in `source` must be rejected.

package/tools/manifest/fixtures/traversal-source/capability.json

@@ -0,0 +1,11 @@
+{
+  "family": "agent-workflow",
+  "schema": 1,
+  "name": "traversal-source",
+  "kind": "execution-backend",
+  "version": "1.0.0",
+  "provides": ["review"],
+  "roles": {
+    "review": { "cmd": "ghost", "source": "../escape/run.sh" }
+  }
+}

package/tools/manifest/fixtures/unknown-schema/capability.json

@@ -0,0 +1,9 @@
+{
+  "family": "agent-workflow",
+  "schema": 2,
+  "name": "from-the-future",
+  "kind": "memory-substrate",
+  "version": "1.0.0",
+  "provides": [],
+  "roles": {}
+}

package/tools/manifest/fixtures/valid/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: fixture-valid
+description: A valid family manifest fixture for validate.test.mjs.
+metadata:
+  version: '1.0.0'
+---
+
+# fixture-valid
+
+Test fixture — a well-formed `capability.json` whose every check passes.

package/tools/manifest/fixtures/valid/bin/run.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+# fixture source script — existence is all the validator checks.
+exit 0

package/tools/manifest/fixtures/valid/capability.json

@@ -0,0 +1,18 @@
+{
+  "family": "agent-workflow",
+  "schema": 1,
+  "name": "fixture-valid",
+  "kind": "execution-backend",
+  "version": "1.0.0",
+  "provides": ["review", "execute"],
+  "roles": {
+    "review": { "cmd": "fixture-review", "source": "bin/run.sh", "modes": ["plan", "code"], "output": "advisory" },
+    "execute": { "cmd": "fixture-exec", "source": "bin/run.sh" }
+  },
+  "detect": {
+    "installed": { "env": "FIXTURE_DIR", "default": "~/.claude/skills/fixture-valid", "file": "SKILL.md" },
+    "deployed": { "file": "docs/ai/.memory-version" }
+  },
+  "cost": "subscription",
+  "quota": { "kind": "subscription", "finite": true }
+}

package/tools/manifest/fixtures/version-mismatch/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: version-drift
+metadata:
+  version: '1.0.0'
+---
+
+# version-drift fixture — capability.json `version` (2.0.0) disagrees with SKILL.md (1.0.0).

package/tools/manifest/fixtures/version-mismatch/capability.json

@@ -0,0 +1,9 @@
+{
+  "family": "agent-workflow",
+  "schema": 1,
+  "name": "version-drift",
+  "kind": "memory-substrate",
+  "version": "2.0.0",
+  "provides": [],
+  "roles": {}
+}

package/tools/manifest/fixtures/win-absolute-source/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: win-absolute-source
+metadata:
+  version: '1.0.0'
+---
+
+# win-absolute-source fixture — a Windows-absolute `source` must be rejected on any platform.

package/tools/manifest/fixtures/win-absolute-source/capability.json

@@ -0,0 +1,11 @@
+{
+  "family": "agent-workflow",
+  "schema": 1,
+  "name": "win-absolute-source",
+  "kind": "execution-backend",
+  "version": "1.0.0",
+  "provides": ["review"],
+  "roles": {
+    "review": { "cmd": "ghost", "source": "C:\\evil\\run.sh" }
+  }
+}

package/tools/manifest/schema.md

@@ -0,0 +1,67 @@
+# `capability.json` — family manifest schema (schema 1)
+
+Owned and shipped by the kit (the composition root). Every `agent-workflow` family member
+ships a `capability.json` at its skill root. Detection is **declarative** (path/env fields, not
+embedded shell — Windows-safe); the installer resolves path fields in Node (tilde + env
+expansion), never via the shell. The validator is [`validate.mjs`](./validate.mjs).
+
+## Fields
+
+| Key | Type | Required | Notes |
+|---|---|---|---|
+| `family` | string | yes | must be `"agent-workflow"` |
+| `schema` | number | yes | `1`. An unknown number → **unsupported** (not invalid). |
+| `name` | string | yes | the skill name |
+| `kind` | string | yes | one of `memory-substrate`, `methodology-engine`, `execution-backend`, `composition-root` |
+| `version` | string | yes | must equal the authoritative version (below), unless `available:false` |
+| `provides` | string[] | yes | subset of the **role vocabulary** |
+| `roles` | object | yes | keys ⊆ `provides`; see *Roles* |
+| `detect` | object | no | `installed` (skill on the machine) + `deployed` (substrate set up in cwd) |
+| `install` / `uninstall` | object | no | `install.npm` is a package name, not a path |
+| `cost` / `quota` / `provenance` | misc | no | informational |
+| `available` | boolean | no | `false` = a declared-but-not-installed stub; skips fs/version checks |
+
+## Role vocabulary
+
+`context | plan | execute | review | probe | synthesize`. Every entry of `provides` and every
+key of `roles` must come from this set, and **`provides` ⊇ `Object.keys(roles)`** (you may
+advertise a capability without a callable role, but never the reverse).
+
+### Roles
+
+Each `roles.<role>` is an object:
+
+- `cmd` (string, required) — the **PATH name** of the wrapper (e.g. `codex-review`). Not a repo
+  path; not validated for existence.
+- `source` (string, required) — the **in-skill script** backing `cmd` (e.g. `bin/codex-review.sh`).
+  Repo-relative within the skill; **must exist**.
+- `template` (string, optional) — an in-skill prompt/template path (e.g.
+  `references/review-prompt.md`); repo-relative, **must exist**.
+- `modes`, `output` (optional) — e.g. `["plan","code"]`, `"advisory"`.
+
+## Path-field rules (Windows-safe, traversal-safe)
+
+- **No absolute paths**, **no `..` traversal**, **no unresolved placeholders** (`{{…}}` / `${…}`)
+  in any field.
+- `source`, `template`, `detect.installed.file` — repo-relative **within the skill**; must exist
+  (skipped for `available:false` stubs).
+- `detect.installed.default` — may be **home-relative** (`~/…`); resolved by the installer.
+- `detect.deployed.file` — **project-relative** (e.g. `docs/ai/.memory-version`); format-checked
+  only (it lives in the target project, not the skill).
+- `detect.installed.env` — an **env var name**, not a path.
+
+## Authoritative version
+
+`version` is matched against `package.json` `version` where one exists, else the skill's
+`SKILL.md` frontmatter `metadata.version` — so a bridge with no `package.json` cannot drift from
+its `SKILL.md`. Skipped only for `available:false` stubs.
+
+## Result classes
+
+- **valid** — schema understood, all checks pass.
+- **unsupported** — `schema` is a number this validator does not understand (forward-compat).
+- **invalid** — schema understood but a check failed.
+
+Runtime callers (the kit's memory detector) treat **unsupported and invalid alike — do not act**,
+fall back to the bundled copy. Authoring/CI runs `validate.mjs --strict` and exits non-zero on
+**unsupported or invalid**.

package/tools/manifest/validate.mjs

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+// Family-wide capability.json validator — OWNED AND SHIPPED BY THE KIT (the composition
+// root legitimately knows the whole family). Pure Node, JSON.parse, dependency-free.
+//
+// Shipped in the kit's tarball + installer PAYLOAD so an *installed* kit can run it as the
+// memory detector (SKILL.md §"delegate-else-fallback"); root CI invokes this SAME file over
+// every real capability.json. It lives in the kit, never in memory (preserving memory's
+// "knows nobody"): a DAG, no cycle.
+//
+// Three result classes:
+//   valid        — well-formed, schema understood, every check passes.
+//   unsupported  — schema number this validator does not understand (forward-compat).
+//   invalid      — schema understood but a check failed (malformed, missing, mismatched).
+// Runtime callers (the kit detector) treat unsupported AND invalid alike: DO NOT act, fall
+// back. Authoring/CI runs with `--strict` and exits non-zero on unsupported OR invalid.
+//
+// Usage:
+//   node validate.mjs <skill-dir>...            # report, always exit 0 (informational)
+//   node validate.mjs --strict <skill-dir>...   # exit 1 if any dir is not "valid"
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, join, isAbsolute } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export const FAMILY = 'agent-workflow';
+export const SUPPORTED_SCHEMA = 1;
+export const KINDS = new Set([
+  'memory-substrate',
+  'methodology-engine',
+  'execution-backend',
+  'composition-root',
+]);
+export const ROLE_VOCAB = new Set(['context', 'plan', 'execute', 'review', 'probe', 'synthesize']);
+
+export const VALID = 'valid';
+export const UNSUPPORTED = 'unsupported';
+export const INVALID = 'invalid';
+
+const hasTraversal = (p) => p.split(/[\\/]/).includes('..');
+const isUnresolved = (s) => /\{\{|\}\}|\$\{/.test(s);
+
+// Cross-platform "absolute-like": POSIX root (/x), Windows drive (C:\ or C:/), UNC (\\host),
+// or a leading backslash. node:path.isAbsolute() alone is platform-dependent, so a Windows path
+// would slip through unchecked on a POSIX CI runner — Windows-safety requires rejecting both.
+const isAbsoluteLike = (p) => isAbsolute(p) || /^[A-Za-z]:[\\/]/.test(p) || /^[\\/]{2}/.test(p) || p.startsWith('\\');
+
+const collectStrings = (val, acc = []) => {
+  if (typeof val === 'string') acc.push(val);
+  else if (Array.isArray(val)) val.forEach((v) => collectStrings(v, acc));
+  else if (val && typeof val === 'object') Object.values(val).forEach((v) => collectStrings(v, acc));
+  return acc;
+};
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---/;
+// Parse the `version:` that is a DIRECT child of the `metadata:` block — not the first `version:`
+// anywhere in the frontmatter (so an unrelated top-level `version:` is ignored) and not a deeper
+// nested `version:` (so `metadata: { foo: { version } }` is ignored). The direct-child indent is
+// fixed by the first child line of the block.
+const readSkillVersion = (text) => {
+  const fm = text.match(FRONTMATTER_RE);
+  if (!fm) return null;
+  const lines = fm[1].split('\n');
+  const metaIdx = lines.findIndex((line) => /^metadata:\s*$/.test(line));
+  if (metaIdx === -1) return null;
+  const block = [];
+  for (const line of lines.slice(metaIdx + 1)) {
+    if (line.trim() === '') continue; // tolerate blank lines inside the block
+    if (/^\S/.test(line)) break; // dedent → left the metadata block
+    block.push(line);
+  }
+  if (block.length === 0) return null;
+  const childIndent = block[0].match(/^(\s+)/)[1];
+  const directChild = new RegExp(`^${childIndent}version:\\s*['"]?(\\d+\\.\\d+\\.\\d+)['"]?\\s*$`);
+  const match = block.map((line) => line.match(directChild)).find(Boolean);
+  return match ? match[1] : null;
+};
+
+// Authoritative version source: package.json where one exists, else SKILL.md
+// frontmatter metadata.version. So a bridge (no package.json) can't drift from its SKILL.md.
+const readAuthoritativeVersion = (skillDir) => {
+  const pkgPath = join(skillDir, 'package.json');
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+      return { version: pkg.version ?? null, from: 'package.json' };
+    } catch {
+      return { version: null, from: 'package.json (unparseable)' };
+    }
+  }
+  const skillPath = join(skillDir, 'SKILL.md');
+  if (existsSync(skillPath)) {
+    return { version: readSkillVersion(readFileSync(skillPath, 'utf8')), from: 'SKILL.md metadata.version' };
+  }
+  return { version: null, from: 'no package.json or SKILL.md' };
+};
+
+export const validateManifest = (skillDir) => {
+  const manifestPath = join(skillDir, 'capability.json');
+  let raw;
+  try {
+    raw = readFileSync(manifestPath, 'utf8');
+  } catch {
+    return { result: INVALID, errors: [`capability.json not found in ${skillDir}`] };
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(raw);
+  } catch (err) {
+    return { result: INVALID, errors: [`malformed JSON: ${err.message}`] };
+  }
+
+  // Valid JSON that is not an object (null, array, string, number) would crash field access —
+  // classify as invalid so runtime callers fall back instead of throwing.
+  if (manifest === null || typeof manifest !== 'object' || Array.isArray(manifest)) {
+    return { result: INVALID, errors: ['top-level capability.json must be a JSON object'] };
+  }
+
+  // Schema gate first — an unknown schema is *unsupported*, distinct from *invalid*.
+  if (typeof manifest.schema !== 'number') {
+    return { result: INVALID, name: manifest.name, errors: ['`schema` missing or not a number'] };
+  }
+  if (manifest.schema !== SUPPORTED_SCHEMA) {
+    return {
+      result: UNSUPPORTED,
+      name: manifest.name,
+      errors: [`unsupported schema ${manifest.schema} (this validator understands ${SUPPORTED_SCHEMA})`],
+    };
+  }
+
+  const errors = [];
+  const requireString = (key) => {
+    if (typeof manifest[key] !== 'string' || !manifest[key]) errors.push(`\`${key}\` must be a non-empty string`);
+  };
+  requireString('family');
+  requireString('name');
+  requireString('kind');
+  requireString('version');
+  if (manifest.family !== FAMILY) errors.push(`\`family\` must be "${FAMILY}"`);
+  if (typeof manifest.kind === 'string' && !KINDS.has(manifest.kind)) errors.push(`unknown \`kind\` "${manifest.kind}"`);
+  if (manifest.available != null && typeof manifest.available !== 'boolean') errors.push('`available`, if present, must be a boolean');
+  if (!Array.isArray(manifest.provides)) errors.push('`provides` must be an array');
+  const rolesOk = manifest.roles != null && typeof manifest.roles === 'object' && !Array.isArray(manifest.roles);
+  if (!rolesOk) errors.push('`roles` must be an object');
+
+  const provides = Array.isArray(manifest.provides) ? manifest.provides : [];
+  for (const p of provides) if (!ROLE_VOCAB.has(p)) errors.push(`\`provides\` lists unknown role "${p}"`);
+  const roles = rolesOk ? manifest.roles : {};
+  for (const key of Object.keys(roles)) {
+    if (!ROLE_VOCAB.has(key)) errors.push(`role "${key}" is not in the role vocabulary`);
+    if (!provides.includes(key)) errors.push(`role "${key}" is missing from \`provides\` (provides ⊇ Object.keys(roles))`);
+  }
+
+  for (const s of collectStrings(manifest)) {
+    if (isUnresolved(s)) errors.push(`unresolved placeholder in "${s}"`);
+  }
+
+  const isStub = manifest.available === false;
+
+  // In-skill path: repo-relative, no absolute, no "~", no "..", and (unless a stub) must exist.
+  const checkInSkillPath = (label, value, mustExist) => {
+    if (typeof value !== 'string' || !value) {
+      errors.push(`${label} must be a non-empty string`);
+      return;
+    }
+    let bad = false;
+    if (isAbsoluteLike(value)) {
+      errors.push(`${label} must not be an absolute path ("${value}")`);
+      bad = true;
+    }
+    if (value.startsWith('~')) {
+      errors.push(`${label} must be repo-relative within the skill, not home-relative ("${value}")`);
+      bad = true;
+    }
+    if (hasTraversal(value)) {
+      errors.push(`${label} must not contain ".." traversal ("${value}")`);
+      bad = true;
+    }
+    if (mustExist && !bad && !existsSync(join(skillDir, value))) {
+      errors.push(`${label} not found in the skill dir: "${value}"`);
+    }
+  };
+
+  const detect = manifest.detect;
+  if (detect != null) {
+    if (typeof detect !== 'object' || Array.isArray(detect)) {
+      errors.push('`detect` must be an object');
+    } else {
+      const isPlainObject = (v) => v != null && typeof v === 'object' && !Array.isArray(v);
+      const inst = detect.installed;
+      if (inst != null && !isPlainObject(inst)) {
+        errors.push('`detect.installed` must be an object');
+      } else if (inst != null) {
+        if (inst.env != null && typeof inst.env !== 'string') errors.push('`detect.installed.env` must be a string (env var name)');
+        if (inst.default != null) {
+          if (typeof inst.default !== 'string') errors.push('`detect.installed.default` must be a string');
+          else {
+            // `default` may be home-relative (~/…); reject only true absolute/traversal forms.
+            if (isAbsoluteLike(inst.default)) errors.push('`detect.installed.default` must not be an absolute path');
+            if (hasTraversal(inst.default)) errors.push('`detect.installed.default` must not contain ".."');
+          }
+        }
+        if (inst.file != null) checkInSkillPath('`detect.installed.file`', inst.file, !isStub);
+      }
+      const dep = detect.deployed;
+      if (dep != null && !isPlainObject(dep)) {
+        errors.push('`detect.deployed` must be an object');
+      } else if (dep != null && dep.file != null) {
+        if (typeof dep.file !== 'string') errors.push('`detect.deployed.file` must be a string');
+        else {
+          if (isAbsoluteLike(dep.file)) errors.push('`detect.deployed.file` must not be an absolute path');
+          if (dep.file.startsWith('~')) errors.push('`detect.deployed.file` must be project-relative, not home-relative');
+          if (hasTraversal(dep.file)) errors.push('`detect.deployed.file` must not contain ".."');
+        }
+      }
+    }
+  }
+
+  for (const [key, role] of Object.entries(roles)) {
+    if (role == null || typeof role !== 'object' || Array.isArray(role)) {
+      errors.push(`role "${key}" must be an object`);
+      continue;
+    }
+    if (typeof role.cmd !== 'string' || !role.cmd) errors.push(`role "${key}".cmd must be a non-empty string (the PATH name)`);
+    if (role.source == null) errors.push(`role "${key}".source is required (the in-skill script; cmd is the PATH name, source is validated)`);
+    else checkInSkillPath(`role "${key}".source`, role.source, !isStub);
+    if (role.template != null) checkInSkillPath(`role "${key}".template`, role.template, !isStub);
+  }
+
+  if (!isStub) {
+    const auth = readAuthoritativeVersion(skillDir);
+    if (auth.version == null) errors.push(`could not resolve an authoritative version (${auth.from})`);
+    else if (typeof manifest.version === 'string' && manifest.version !== auth.version) {
+      errors.push(`\`version\` "${manifest.version}" != ${auth.from} "${auth.version}"`);
+    }
+  }
+
+  return {
+    result: errors.length ? INVALID : VALID,
+    name: manifest.name,
+    kind: manifest.kind,
+    available: manifest.available !== false, // false only when explicitly declared a stub
+    errors,
+  };
+};
+
+const main = (argv) => {
+  const strict = argv.includes('--strict');
+  const dirs = argv.filter((a) => a !== '--strict');
+  if (dirs.length === 0) {
+    console.error('usage: validate.mjs [--strict] <skill-dir>...');
+    process.exit(2);
+  }
+  let notValid = 0;
+  for (const dir of dirs) {
+    const report = validateManifest(resolve(dir));
+    console.log(`[${report.result.toUpperCase()}] ${dir}${report.name ? ` (${report.name})` : ''}`);
+    for (const err of report.errors) console.log(`    - ${err}`);
+    if (report.result !== VALID) notValid += 1;
+  }
+  if (strict && notValid > 0) process.exit(1);
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) main(process.argv.slice(2));

package/tools/manifest/validate.test.mjs

@@ -0,0 +1,73 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { validateManifest, VALID, UNSUPPORTED, INVALID } from './validate.mjs';
+
+const FIX = join(dirname(fileURLToPath(import.meta.url)), 'fixtures');
+const at = (name) => join(FIX, name);
+
+describe('validateManifest — result classes', () => {
+  it('valid fixture → valid', () => {
+    const r = validateManifest(at('valid'));
+    assert.equal(r.result, VALID, r.errors.join('; '));
+    assert.deepEqual(r.errors, []);
+  });
+
+  it('available:false stub → valid (version + fs existence checks skipped)', () => {
+    const r = validateManifest(at('stub'));
+    assert.equal(r.result, VALID, r.errors.join('; '));
+  });
+
+  it('unknown schema → unsupported (distinct from invalid)', () => {
+    const r = validateManifest(at('unknown-schema'));
+    assert.equal(r.result, UNSUPPORTED);
+  });
+
+  it('a non-object root (JSON null) → invalid, not a crash', () => {
+    const r = validateManifest(at('null-root'));
+    assert.equal(r.result, INVALID);
+    assert.ok(r.errors.some((e) => /must be a JSON object/.test(e)));
+  });
+
+  it('reads metadata.version, not a stray top-level version: → valid', () => {
+    const r = validateManifest(at('metadata-version'));
+    assert.equal(r.result, VALID, r.errors.join('; '));
+  });
+
+  it('reads the DIRECT metadata.version, ignoring a deeper nested version: → valid', () => {
+    const r = validateManifest(at('nested-version-decoy'));
+    assert.equal(r.result, VALID, r.errors.join('; '));
+  });
+});
+
+describe('validateManifest — negative fixtures MUST fail (strict)', () => {
+  const mustFail = [
+    ['malformed-json', /malformed JSON/],
+    ['missing-key', /`name` must be a non-empty string/],
+    ['provides-roles-mismatch', /missing from `provides`/],
+    ['version-mismatch', /`version` "2\.0\.0" != /],
+    ['missing-source', /not found in the skill dir/],
+    ['detect-array', /`detect\.installed` must be an object/],
+    ['win-absolute-source', /must not be an absolute path/],
+    ['traversal-source', /must not contain "\.\." traversal/],
+    ['bad-available', /`available`, if present, must be a boolean/],
+  ];
+  for (const [name, pattern] of mustFail) {
+    it(`${name} → invalid`, () => {
+      const r = validateManifest(at(name));
+      assert.equal(r.result, INVALID);
+      assert.ok(
+        r.errors.some((e) => pattern.test(e)),
+        `expected an error matching ${pattern} in: ${r.errors.join(' | ')}`,
+      );
+    });
+  }
+});
+
+describe('validateManifest — path-field hardening', () => {
+  it('valid fixture allows a home-relative detect.installed.default (~) but rejects nothing else', () => {
+    const r = validateManifest(at('valid'));
+    assert.ok(!r.errors.some((e) => /default/.test(e)));
+  });
+});

package/tools/methodology-slot.md

@@ -0,0 +1 @@
+> **Workflow methodology** — plan → execute → review. Plans are ephemeral `docs/plans/*.md` (gitignored, **never committed**); every Plan ends with a mandatory **Phase: Cleanup**; series order lives in `docs/plans/queue.md`. Full vocabulary, lifecycle, and the plan-then-execute split live in the project's **planning skill** (it overrides the generic `writing-plans`); summary in `docs/ai/agent_rules.md` §5.