skill-family-engineering-kit 0.2.1 → 0.3.0

package/candidate/projection-bundle-cli.mjs

@@ -1,22 +1,64 @@
 #!/usr/bin/env node
+import path from "node:path";
 import { buildQuickstartProfileProjection } from "./profile-bundle.mjs";
 
+/**
+ * Build-time CLI for the Quickstart Profile v2 offline bundle. It only emits
+ * the projection manifest on stdout; diagnostics go to stderr and every
+ * argument or build failure exits 2. Writing stays with runProjection.
+ */
+
+const USAGE = [
+  "usage: projection-bundle-cli.mjs",
+  "  [--target-prefix <relative-path>]",
+  "  --consumer-schema-root <absolute-build-time-root>",
+  "  --consumer-schema <relative-path>   (repeatable)",
+  "  --source-repository <identity>",
+  "  --source-base-commit <identity>",
+].join("\n");
+
+function fail(message) {
+  process.stderr.write(`${message}\n${USAGE}\n`);
+  process.exit(2);
+}
+
 const args = process.argv.slice(2);
-let targetPrefix;
-if (args.length > 0) {
-  if (args.length !== 2 || args[0] !== "--target-prefix") {
-    process.stderr.write("usage: projection-bundle-cli.mjs [--target-prefix <relative-path>]\n");
-    process.exitCode = 2;
-  } else {
-    targetPrefix = args[1];
+const options = { consumerSchemaPaths: [] };
+for (let index = 0; index < args.length; index += 1) {
+  const flag = args[index];
+  const next = args[index + 1];
+  switch (flag) {
+    case "--target-prefix":
+    case "--consumer-schema-root":
+    case "--consumer-schema":
+    case "--source-repository":
+    case "--source-base-commit":
+      if (next === undefined) fail(`missing value for ${flag}`);
+      index += 1;
+      if (flag === "--consumer-schema") options.consumerSchemaPaths.push(next);
+      else if (flag === "--target-prefix") options.targetPrefix = next;
+      else if (flag === "--consumer-schema-root") options.consumerSchemaRoot = next;
+      else if (flag === "--source-repository") options.sourceRepository = next;
+      else options.sourceBaseCommit = next;
+      break;
+    default:
+      fail(`unknown argument: ${flag}`);
   }
 }
-if (process.exitCode !== 2) {
-  try {
-    const { manifest } = await buildQuickstartProfileProjection({ targetPrefix });
-    process.stdout.write(`${JSON.stringify(manifest, null, 2)}\n`);
-  } catch (cause) {
-    process.stderr.write(`${cause?.message ?? String(cause)}\n`);
-    process.exitCode = 2;
-  }
+if (!options.consumerSchemaRoot) fail("--consumer-schema-root is required");
+if (!path.isAbsolute(options.consumerSchemaRoot)) {
+  fail("--consumer-schema-root must be an absolute directory");
+}
+if (options.consumerSchemaPaths.length === 0) {
+  fail("at least one --consumer-schema is required");
+}
+if (!options.sourceRepository) fail("--source-repository is required");
+if (!options.sourceBaseCommit) fail("--source-base-commit is required");
+
+try {
+  const { manifest } = await buildQuickstartProfileProjection(options);
+  process.stdout.write(`${JSON.stringify(manifest, null, 2)}\n`);
+} catch (cause) {
+  process.stderr.write(`${cause?.message ?? String(cause)}\n`);
+  process.exit(2);
 }

package/candidate/skill-naming-cli.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import { checkPluginSkillNaming } from "./skill-naming.mjs";
+
+/**
+ * Build-time CLI for the candidate plugin skill naming check. It only emits
+ * the report on stdout; diagnostics go to stderr. Exit codes: 0 = every
+ * skill passes, 1 = at least one rule FAIL, 2 = usage or mechanism error.
+ * The CLI never writes anywhere.
+ */
+
+const USAGE = [
+  "usage: skill-naming-cli.mjs",
+  "  --skills-root <directory>     (required; each immediate child with SKILL.md is one published skill)",
+  "  --plugin-slug <slug>          (required; the published plugin slug, required as description signal)",
+  "  --name-prefix <prefix>        (optional approved name prefix; defaults to the plugin slug)",
+  "  --domain-signal <word>        (repeatable; extra domain words accepted as description signals)",
+  "  --policy <path>               (optional; defaults to the bundled candidate policy)",
+].join("\n");
+
+function fail(message) {
+  process.stderr.write(`${message}\n${USAGE}\n`);
+  process.exit(2);
+}
+
+const args = process.argv.slice(2);
+const options = { domainSignals: [] };
+for (let index = 0; index < args.length; index += 1) {
+  const flag = args[index];
+  const next = args[index + 1];
+  switch (flag) {
+    case "--skills-root":
+    case "--plugin-slug":
+    case "--name-prefix":
+    case "--domain-signal":
+    case "--policy":
+      if (next === undefined) fail(`missing value for ${flag}`);
+      index += 1;
+      if (flag === "--skills-root") options.skillsRoot = next;
+      else if (flag === "--plugin-slug") options.pluginSlug = next;
+      else if (flag === "--name-prefix") options.namePrefix = next;
+      else if (flag === "--domain-signal") options.domainSignals.push(next);
+      else options.policyPath = next;
+      break;
+    default:
+      fail(`unknown argument: ${flag}`);
+  }
+}
+if (!options.skillsRoot) fail("--skills-root is required");
+if (!options.pluginSlug) fail("--plugin-slug is required");
+
+try {
+  const report = await checkPluginSkillNaming(options);
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  process.exit(report.ok ? 0 : 1);
+} catch (cause) {
+  const kind = cause && cause.details && cause.details.kind ? ` (${cause.details.kind})` : "";
+  process.stderr.write(`${cause?.code ?? "SFC2004"}${kind}: ${cause?.message ?? String(cause)}\n`);
+  process.exit(2);
+}

package/candidate/skill-naming-policy.json

@@ -0,0 +1,46 @@
+{
+  "schemaVersion": 1,
+  "kind": "skill-family.skill-naming-policy",
+  "policyVersion": "1.0.0",
+  "status": "candidate",
+  "summary": "Plugin skill naming and description policy: every published skill name carries the plugin prefix, every frontmatter description carries a domain signal, and routing entry skills declare plugin-internal routing scope.",
+  "pluginSlugPattern": "^[a-z][a-z0-9-]*$",
+  "skillName": {
+    "ruleId": "SNR-001",
+    "summary": "Every published skill name must be <plugin-slug>-<suffix>; bare generic names are forbidden.",
+    "suffixPattern": "[a-z0-9][a-z0-9-]*",
+    "reservedBareNames": ["help", "setup", "quickstart", "where-am-i"],
+    "additionalApprovedPatterns": [],
+    "note": "Equivalent namespace forms are only valid when their regular expression is explicitly approved and registered in additionalApprovedPatterns; a reserved bare name stays forbidden even then."
+  },
+  "description": {
+    "ruleId": "SNR-002",
+    "summary": "The frontmatter description must contain a domain signal (the plugin slug or a declared domain word) and must not consist of a bare global trigger phrase.",
+    "forbiddenGlobalTriggers": [
+      "what can this plugin do",
+      "what can you do",
+      "how to start",
+      "how do i start",
+      "is my environment ready",
+      "你能做什么",
+      "怎么开始",
+      "我的环境准备好了吗"
+    ]
+  },
+  "routingEntry": {
+    "ruleId": "SNR-003",
+    "summary": "A routing entry skill must name its plugin slug in the description (plugin-internal routing scope) and must not imply global arbitration.",
+    "suffixes": ["help", "quickstart", "where-am-i"],
+    "forbiddenGlobalScopePhrases": [
+      "across all plugins",
+      "all installed plugins",
+      "global routing",
+      "global arbitration",
+      "routes every plugin",
+      "全局路由",
+      "全局仲裁",
+      "所有插件",
+      "跨插件仲裁"
+    ]
+  }
+}

package/candidate/skill-naming.mjs

@@ -0,0 +1,280 @@
+import { readFile, readdir, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Candidate plugin skill naming checker (unstable).
+ *
+ * Mechanically evaluates the cross-repository skill naming and description
+ * policy (candidate/skill-naming-policy.json) over one plugin skills root:
+ * every immediate subdirectory that carries a SKILL.md is one published
+ * skill, and its frontmatter `name` / `description` are checked against the
+ * three frozen rules:
+ *
+ *   SNR-001  name prefix        — name must be `<plugin-slug>-<suffix>`
+ *                                 (or match an explicitly approved extra
+ *                                 pattern); reserved bare names are always
+ *                                 forbidden;
+ *   SNR-002  description signal — description must contain the plugin slug
+ *                                 or a caller-declared domain word, and must
+ *                                 not consist of a bare global trigger
+ *                                 phrase;
+ *   SNR-003  routing scope      — routing entry skills (policy suffixes)
+ *                                 must name the plugin slug in the
+ *                                 description and must not imply global
+ *                                 arbitration.
+ *
+ * The module only reads; it never writes, never consults the network, the
+ * clock, or Git. Every rule outcome is reported per skill as PASS or FAIL;
+ * the report's `ok` is the AND of all rule outcomes.
+ */
+
+export const SKILL_NAMING_POLICY_PATH = fileURLToPath(
+  new URL("./skill-naming-policy.json", import.meta.url),
+);
+
+export const SKILL_NAMING_RULE_IDS = Object.freeze(["SNR-001", "SNR-002", "SNR-003"]);
+
+function namingError(kind, message, details) {
+  const error = new Error(message);
+  error.code = "SFC2004";
+  error.details = { ...(details ?? {}), kind };
+  return error;
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function unquote(value) {
+  const trimmed = value.trim();
+  if (
+    trimmed.length >= 2 &&
+    ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+      (trimmed.startsWith("'") && trimmed.endsWith("'")))
+  ) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+/**
+ * Line-based frontmatter extraction (no YAML dependency): the document must
+ * open with a `---` line and close with another `---` line; `name` and
+ * `description` are top-level keys, optionally quoted, optionally continued
+ * on indented lines (plain multi-line or `|`/`>` block scalars).
+ */
+export function parseSkillFrontmatter(text) {
+  if (typeof text !== "string" || !text.startsWith("---\n")) {
+    throw namingError("frontmatter-missing", "SKILL.md does not start with a frontmatter fence");
+  }
+  const lines = text.split("\n");
+  const end = lines.indexOf("---", 1);
+  if (end === -1) {
+    throw namingError("frontmatter-unclosed", "SKILL.md frontmatter fence is not closed");
+  }
+  const fields = {};
+  for (let index = 1; index < end; index += 1) {
+    const match = /^([A-Za-z][A-Za-z0-9_-]*):[ \t]*(.*)$/.exec(lines[index]);
+    if (!match) continue;
+    const [, key, rawValue] = match;
+    let value = rawValue;
+    if (value === "" || value === "|" || value === ">" || value === "|-" || value === ">-") {
+      const collected = [];
+      for (let follow = index + 1; follow < end; follow += 1) {
+        const line = lines[follow];
+        if (/^[ \t]+\S/.test(line)) collected.push(line.trim());
+        else if (line.trim() === "") collected.push("");
+        else break;
+      }
+      value = collected.join(" ").trim();
+      index += collected.length;
+    }
+    fields[key] = unquote(value);
+  }
+  return { name: fields.name, description: fields.description };
+}
+
+/** Loads and shape-validates a naming policy document. */
+export async function loadSkillNamingPolicy(policyPath) {
+  const resolved = policyPath ?? SKILL_NAMING_POLICY_PATH;
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(resolved, "utf8"));
+  } catch (cause) {
+    throw namingError(
+      cause && cause.code === "ENOENT" ? "policy-missing" : "policy-parse-failed",
+      `skill naming policy is not readable JSON: ${resolved}`,
+    );
+  }
+  if (!parsed || parsed.kind !== "skill-family.skill-naming-policy" || parsed.schemaVersion !== 1) {
+    throw namingError("policy-invalid", "skill naming policy must carry schemaVersion 1 and kind skill-family.skill-naming-policy");
+  }
+  for (const section of ["skillName", "description", "routingEntry"]) {
+    if (!parsed[section] || typeof parsed[section].ruleId !== "string") {
+      throw namingError("policy-invalid", `skill naming policy lacks a usable ${section} section`);
+    }
+  }
+  return parsed;
+}
+
+function normalizePhrase(value) {
+  return String(value ?? "")
+    .toLocaleLowerCase("en-US")
+    .replace(/[\s\p{P}\p{S}]+/gu, " ")
+    .trim();
+}
+
+function ruleOutcome(ruleId, ok, message) {
+  return { ruleId, status: ok ? "PASS" : "FAIL", ...(ok ? {} : { message }) };
+}
+
+function checkNameRule(name, namePrefix, policy) {
+  const { suffixPattern, reservedBareNames, additionalApprovedPatterns } = policy.skillName;
+  if (typeof name !== "string" || name.length === 0) {
+    return ruleOutcome("SNR-001", false, "frontmatter lacks a usable name");
+  }
+  if (reservedBareNames.includes(name)) {
+    return ruleOutcome("SNR-001", false, `reserved bare generic name is forbidden: ${name}`);
+  }
+  const prefixed = new RegExp(`^${escapeRegExp(namePrefix)}-(?:${suffixPattern})$`).test(name);
+  const approved = (Array.isArray(additionalApprovedPatterns) ? additionalApprovedPatterns : []).some(
+    (pattern) => new RegExp(pattern).test(name),
+  );
+  return prefixed || approved
+    ? ruleOutcome("SNR-001", true)
+    : ruleOutcome("SNR-001", false, `name must be ${namePrefix}-<suffix> or an approved namespace form: ${name}`);
+}
+
+function checkDescriptionRule(description, slug, domainSignals, policy) {
+  if (typeof description !== "string" || description.trim().length === 0) {
+    return ruleOutcome("SNR-002", false, "frontmatter lacks a usable description");
+  }
+  const lowered = description.toLocaleLowerCase("en-US");
+  const signals = [slug, ...domainSignals].filter((signal) => typeof signal === "string" && signal.length > 0);
+  if (!signals.some((signal) => lowered.includes(signal.toLocaleLowerCase("en-US")))) {
+    return ruleOutcome(
+      "SNR-002",
+      false,
+      "description carries no domain signal (plugin slug or a declared domain word)",
+    );
+  }
+  const normalized = normalizePhrase(description);
+  const bareTrigger = (policy.description.forbiddenGlobalTriggers ?? []).find(
+    (trigger) => normalizePhrase(trigger) === normalized,
+  );
+  if (bareTrigger !== undefined) {
+    return ruleOutcome("SNR-002", false, `description is a bare global trigger phrase: ${bareTrigger}`);
+  }
+  return ruleOutcome("SNR-002", true);
+}
+
+function checkRoutingRule(name, description, slug, namePrefix, policy) {
+  const suffixes = policy.routingEntry.suffixes ?? [];
+  const prefix = `${namePrefix}-`;
+  const suffix = typeof name === "string" && name.startsWith(prefix) ? name.slice(prefix.length) : null;
+  if (suffix === null || !suffixes.includes(suffix)) {
+    return ruleOutcome("SNR-003", true); // not a routing entry skill: vacuous pass
+  }
+  const lowered = typeof description === "string" ? description.toLocaleLowerCase("en-US") : "";
+  if (!lowered.includes(slug.toLocaleLowerCase("en-US"))) {
+    return ruleOutcome(
+      "SNR-003",
+      false,
+      "routing entry skill must name the plugin slug to declare plugin-internal routing scope",
+    );
+  }
+  const scopePhrase = (policy.routingEntry.forbiddenGlobalScopePhrases ?? []).find((phrase) =>
+    lowered.includes(phrase.toLocaleLowerCase("en-US")),
+  );
+  if (scopePhrase !== undefined) {
+    return ruleOutcome("SNR-003", false, `routing entry skill implies global arbitration: ${scopePhrase}`);
+  }
+  return ruleOutcome("SNR-003", true);
+}
+
+/**
+ * Checks every published skill under one skills root.
+ * Options: { skillsRoot, pluginSlug, namePrefix?, domainSignals?, policyPath? }.
+ * namePrefix is the approved name prefix used by SNR-001/SNR-003 and defaults
+ * to pluginSlug; the reference implementation shows the two can differ (an
+ * approved short prefix), while SNR-002/SNR-003 still require the full plugin
+ * slug as the description signal.
+ * Returns the report document; throws a coded error only for unusable
+ * inputs (missing root, invalid slug, unreadable policy).
+ */
+export async function checkPluginSkillNaming({ skillsRoot, pluginSlug, namePrefix, domainSignals = [], policyPath } = {}) {
+  const policy = await loadSkillNamingPolicy(policyPath);
+  if (typeof pluginSlug !== "string" || !new RegExp(policy.pluginSlugPattern).test(pluginSlug)) {
+    throw namingError("invalid-plugin-slug", "pluginSlug must satisfy the policy plugin slug pattern", {
+      pattern: policy.pluginSlugPattern,
+    });
+  }
+  const effectivePrefix = namePrefix ?? pluginSlug;
+  if (typeof effectivePrefix !== "string" || !new RegExp(policy.pluginSlugPattern).test(effectivePrefix)) {
+    throw namingError("invalid-name-prefix", "namePrefix must satisfy the policy plugin slug pattern", {
+      pattern: policy.pluginSlugPattern,
+    });
+  }
+  if (typeof skillsRoot !== "string" || skillsRoot.length === 0) {
+    throw namingError("invalid-skills-root", "skillsRoot is required");
+  }
+  const rootAbs = await realpath(path.resolve(skillsRoot)).catch(() => null);
+  if (rootAbs === null || !(await stat(rootAbs)).isDirectory()) {
+    throw namingError("invalid-skills-root", `skills root is not an existing directory: ${skillsRoot}`);
+  }
+
+  const directories = (await readdir(rootAbs, { withFileTypes: true }))
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort((left, right) => left.localeCompare(right));
+
+  const skills = [];
+  for (const directory of directories) {
+    const relPath = `${directory}/SKILL.md`;
+    let text = null;
+    try {
+      const candidate = path.join(rootAbs, directory, "SKILL.md");
+      if ((await stat(candidate)).isFile()) text = await readFile(candidate, "utf8");
+    } catch {
+      text = null;
+    }
+    if (text === null) continue; // not a published skill directory
+    let frontmatter = { name: undefined, description: undefined };
+    let parseFailure = null;
+    try {
+      frontmatter = parseSkillFrontmatter(text);
+    } catch (cause) {
+      parseFailure = cause && cause.message ? cause.message : String(cause);
+    }
+    const rules =
+      parseFailure !== null
+        ? SKILL_NAMING_RULE_IDS.map((ruleId) => ruleOutcome(ruleId, false, parseFailure))
+        : [
+            checkNameRule(frontmatter.name, effectivePrefix, policy),
+            checkDescriptionRule(frontmatter.description, pluginSlug, domainSignals, policy),
+            checkRoutingRule(frontmatter.name, frontmatter.description, pluginSlug, effectivePrefix, policy),
+          ];
+    skills.push({
+      directory,
+      path: relPath,
+      name: frontmatter.name ?? null,
+      rules,
+      ok: rules.every((rule) => rule.status === "PASS"),
+    });
+  }
+
+  return {
+    kind: "skill-family.skill-naming-report",
+    schemaVersion: 1,
+    policyVersion: policy.policyVersion,
+    pluginSlug,
+    namePrefix: effectivePrefix,
+    skillsRoot: rootAbs,
+    skillCount: skills.length,
+    ok: skills.every((skill) => skill.ok),
+    skills,
+    policy:
+      "skill naming check is diagnosis only: it never writes and never renames; violations must be resolved by the owning plugin",
+  };
+}

package/docs/agents/capability-catalog.en.json

@@ -505,7 +505,7 @@
         "Need to freely author a report from open business outputs (forbidden)"
       ],
       "prerequisites": [
-        "REPORT_RENDERER_NAME / VERSION come from their respective packages (currently 0.2.1)",
+        "REPORT_RENDERER_NAME / VERSION come from their respective packages (currently 0.3.0)",
         "SUPPORTED_REPORT_LOCALES = [zh-CN, en-US]"
       ],
       "inputs": [
@@ -1430,7 +1430,7 @@
     },
     {
       "id": "foundation.contracts.quickstart-profile-candidate",
-      "intent": "Expose the candidate Quickstart Resource, Task, and Result schemas through skill-family-contracts/candidate/quickstart-profile for exact-version integration trials.",
+      "intent": "Expose the Quickstart Profile v2 protocol and real-$id Resource, Task, and Result schema collection through skill-family-contracts/candidate/quickstart-profile for exact-version integration trials.",
       "useWhen": [
         "Need to inspect or validate the candidate Resource, Task, or Result shape before it is proposed for the frozen registry",
         "The consumer can pin the exact skill-family-contracts package version and isolate candidate imports from its stable API"
@@ -1458,6 +1458,7 @@
         "An invalid candidate document returns valid:false with Ajv findings"
       ],
       "invariants": [
+        "The sole business-neutral operation is execute-method; method identifiers and domain schemas remain consumer-owned",
         "Candidate schemas remain absent from src/registry.json and do not expand the 18 stable object classes",
         "Stability is candidate: a later minor release may change or remove this subpath"
       ],
@@ -1502,7 +1503,7 @@
         "verifyQuickstartExchange converts a failure into {valid:false, code, message, details}"
       ],
       "invariants": [
-        "The Result must bind the exact Task digest, observation digest, operation identity, and correlation fields",
+        "The Result must bind the exact Task digest, real Resource bytes, globally unique Resource ids, operation identity, correlation fields, and the complete evidence-binding set",
         "Stability is candidate: a later minor release may change or remove this subpath"
       ],
       "ownedByCaller": [
@@ -1516,35 +1517,37 @@
     },
     {
       "id": "foundation.kit.quickstart-profile-candidate",
-      "intent": "Build a deterministic, self-contained Quickstart projection manifest through skill-family-engineering-kit/candidate/quickstart-profile.",
+      "intent": "Build a deterministic Quickstart Profile v2 offline Bundle with standalone validators selected by schema $id through skill-family-engineering-kit/candidate/quickstart-profile.",
       "useWhen": [
         "Need to trial the candidate Quickstart schemas and runner in a target using the stable projection authorization boundary",
-        "Need provenance and dependency-closure digests for the generated candidate bundle"
+        "Need complete source, consumer-schema, payload, tool-version, and license provenance for the generated Bundle"
       ],
       "doNotUseWhen": [
         "Need a stable Quickstart API or a fifth top-level Kit command",
         "Need to bypass target manifest authorization or handwritten-file protection"
       ],
       "prerequisites": [
-        "Install exact matching versions of all three Foundation packages",
+        "Install exact matching 0.3.0 versions of all three Foundation packages",
         "The target prefix is a contained relative POSIX path"
       ],
       "inputs": [
-        "Optional contained targetPrefix",
+        "Contained targetPrefix, consumerSchemaRoot, and an explicit relative consumer-schema path set",
+        "Frozen sourceRepository and sourceBaseCommit identity",
         "Exact installed Contracts, Harness, and Kit package bytes"
       ],
       "outputs": [
-        "A projection manifest and provenance record with source, runtime dependency, and bundle digests"
+        "A projection manifest and provenance record with Foundation sources, consumer schemas, payload digests, tool versions, and licenses"
       ],
       "sideEffects": [
-        "Builds the manifest in memory and reads installed package files",
+        "Builds the manifest in memory and reads installed package plus explicit consumer-schema files",
         "Performs no writes; callers pass the manifest to stable runProjection for authorized writes"
       ],
       "failureSemantics": [
         "An invalid targetPrefix throws TypeError",
-        "A missing or inconsistent installed dependency closure rejects the build; runProjection reports its own stable projection failures"
+        "Duplicate schema ids, bad references, mixed dialects, unsupported formats, path escapes, or missing source identity reject the build; runProjection reports its own stable projection failures"
       ],
       "invariants": [
+        "The Bundle contains no node_modules or runtime Ajv and runs without installed Foundation packages or network access",
         "The helper adds no top-level Kit command and never bypasses runProjection",
         "Stability is candidate: a later minor release may change or remove this subpath"
       ],

package/docs/agents/capability-catalog.json

@@ -875,10 +875,11 @@
       "since": "0.2.1",
       "stability": "candidate",
       "entrypoints": [
-        "skill-family-contracts/candidate/quickstart-profile: QUICKSTART_PROTOCOL, quickstartProfileSchemas, validateQuickstartProfileDocument (packages/skill-family-contracts/candidate/quickstart-profile/index.mjs)"
+        "skill-family-contracts/candidate/quickstart-profile: QUICKSTART_PROTOCOL, QUICKSTART_PROFILE_VERSION, loadQuickstartProtocol, quickstartProfileSchemas, listQuickstartProfileSchemas, validateQuickstartProfileDocument (packages/skill-family-contracts/candidate/quickstart-profile/index.mjs)"
       ],
       "sourceRefs": [
         "packages/skill-family-contracts/candidate/quickstart-profile/index.mjs",
+        "packages/skill-family-contracts/candidate/quickstart-profile/protocol.json",
         "packages/skill-family-contracts/candidate/quickstart-profile/resource.schema.json",
         "packages/skill-family-contracts/candidate/quickstart-profile/task.schema.json",
         "packages/skill-family-contracts/candidate/quickstart-profile/result.schema.json"
@@ -897,7 +898,7 @@
       "since": "0.2.1",
       "stability": "candidate",
       "entrypoints": [
-        "skill-family-harness-node/candidate/quickstart-profile: createObservationResource, verifyObservationResource, createQuickstartTask, wrapQuickstartResult, assertQuickstartExchange, verifyQuickstartExchange (packages/skill-family-harness-node/candidate/quickstart-profile.mjs)"
+        "skill-family-harness-node/candidate/quickstart-profile: createObservationResource, verifyResourceBytes, verifyObservationResource, createQuickstartTask, wrapQuickstartResult, assertQuickstartExchange, verifyQuickstartExchange, canonicalJson, computeResourceClosure, digestBytes, digestDocument (packages/skill-family-harness-node/candidate/quickstart-profile.mjs)"
       ],
       "sourceRefs": [
         "packages/skill-family-harness-node/candidate/quickstart-profile.mjs"

package/docs/agents/capability-catalog.zh-CN.json

@@ -505,7 +505,7 @@
         "需要从开放业务 outputs 自由编报告（禁止）"
       ],
       "prerequisites": [
-        "REPORT_RENDERER_NAME / VERSION 取自各自 package（当前 0.2.1）",
+        "REPORT_RENDERER_NAME / VERSION 取自各自 package（当前 0.3.0）",
         "SUPPORTED_REPORT_LOCALES = [zh-CN, en-US]"
       ],
       "inputs": [
@@ -1430,7 +1430,7 @@
     },
     {
       "id": "foundation.contracts.quickstart-profile-candidate",
-      "intent": "通过 skill-family-contracts/candidate/quickstart-profile 公开候选 Quickstart Resource、Task 与 Result Schema，供锁定精确版本的接入试验使用",
+      "intent": "通过 skill-family-contracts/candidate/quickstart-profile 公开 Quickstart Profile v2 协议与按真实 $id 索引的 Resource、Task、Result Schema 集合，供锁定精确版本的接入试验使用",
       "useWhen": [
         "需要在提议进入冻结登记表前检查或校验候选 Resource、Task、Result 形状",
         "调用方能够锁定 skill-family-contracts 精确版本，并把 candidate 导入隔离在自身稳定 API 之外"
@@ -1458,6 +1458,7 @@
         "候选文档无效时返回 valid:false 与 Ajv 发现"
       ],
       "invariants": [
+        "唯一业务中立操作为 execute-method；method 标识与领域 Schema 继续归消费者所有",
         "候选 Schema 不进入 src/registry.json，也不扩张 18 类稳定对象",
         "稳定性为 candidate：后续小版本可以修改或移除该子路径"
       ],
@@ -1502,7 +1503,7 @@
         "verifyQuickstartExchange 把失败转成 {valid:false, code, message, details}"
       ],
       "invariants": [
-        "Result 必须绑定精确 Task 摘要、observation 摘要、operation 身份与 correlation 字段",
+        "Result 必须绑定精确 Task 摘要、真实 Resource 字节、全局唯一 Resource id、operation 身份、correlation 字段与完整 evidence binding 集合",
         "稳定性为 candidate：后续小版本可以修改或移除该子路径"
       ],
       "ownedByCaller": [
@@ -1516,35 +1517,37 @@
     },
     {
       "id": "foundation.kit.quickstart-profile-candidate",
-      "intent": "通过 skill-family-engineering-kit/candidate/quickstart-profile 构建确定、自包含的 Quickstart 投影 manifest",
+      "intent": "通过 skill-family-engineering-kit/candidate/quickstart-profile 构建确定性的 Quickstart Profile v2 离线 Bundle，并按 Schema $id 选择 standalone validator",
       "useWhen": [
         "需要通过稳定投影授权边界，在目标中试用候选 Quickstart Schema 与 runner",
-        "需要取得候选投影包的来源摘要、运行依赖闭包摘要与 bundle 摘要"
+        "需要取得完整的来源、消费者 Schema、payload、工具版本与许可证 provenance"
       ],
       "doNotUseWhen": [
         "需要稳定 Quickstart API 或第五个 Kit 顶层命令",
         "需要绕过目标 manifest 授权或手写文件保护"
       ],
       "prerequisites": [
-        "安装精确匹配的三个 Foundation 包版本",
+        "安装精确匹配的三个 Foundation 0.3.0 包版本",
         "targetPrefix 是受收容的 POSIX 相对路径"
       ],
       "inputs": [
-        "可选的受收容 targetPrefix",
+        "受收容 targetPrefix、consumerSchemaRoot 与显式消费者 Schema 相对路径集合",
+        "冻结的 sourceRepository 与 sourceBaseCommit 身份",
         "已安装 Contracts、Harness 与 Kit 的精确包字节"
       ],
       "outputs": [
-        "投影 manifest 与 provenance 记录，包含 source、运行依赖和 bundle 摘要"
+        "投影 manifest 与 provenance 记录，包含 Foundation 来源、消费者 Schema、payload 摘要、工具版本与许可证"
       ],
       "sideEffects": [
-        "在内存中构建 manifest，并读取已安装包文件",
+        "在内存中构建 manifest，并读取已安装包文件与显式消费者 Schema 文件",
         "不执行写入；调用方把 manifest 交给稳定 runProjection 后才发生受权写入"
       ],
       "failureSemantics": [
         "targetPrefix 无效时抛出 TypeError",
-        "已安装依赖闭包缺失或不一致时拒绝构建；runProjection 另行报告稳定投影失败"
+        "重复 Schema id、坏引用、混合方言、不支持的 format、路径越界或来源身份缺失时拒绝构建；runProjection 另行报告稳定投影失败"
       ],
       "invariants": [
+        "Bundle 不含 node_modules 或运行时 Ajv，不依赖已安装 Foundation 包或网络",
         "辅助函数不增加 Kit 顶层命令，也不绕过 runProjection",
         "稳定性为 candidate：后续小版本可以修改或移除该子路径"
       ],