skilldrop-cli 0.15.1 → 0.16.1

package/bin/skilldrop.js

@@ -51,9 +51,11 @@ Usage:
                                           (--no-skills for the loop alone) (RFC-0028)
   skilldrop install --panel review        install the review panel — the 3 reviewer subagents +
                                           the pre-merge-review orchestrator that fires them (RFC-0020)
-  skilldrop update [--force]              re-copy installed skills whose version changed; files
+  skilldrop update [--force] [--changed]  re-copy installed skills whose version changed; files
                                           you edited are kept and the new copy lands beside them
-                                          as <file>.upstream (--force overwrites) (RFC-0032)
+                                          as <file>.upstream (--force overwrites) (RFC-0032).
+                                          Files changed upstream under the same version are named,
+                                          not taken, unless you add --changed (RFC-0039)
   skilldrop outdated                      show installed vs current versions, change nothing
   skilldrop diff <skill> [--stat]         what differs between your installed copy and the catalog's —
                                           your edits, upstream changes, or both
@@ -81,7 +83,8 @@ Catalogs:
   (default)          the catalog bundled with this package
   --from <dir|url>   a skilldrop catalog (packs/<pack>/skills/<name>/ or flat skills/<name>/) OR
                      an agentbundle one (packs/<pack>/.apm/skills/<name>/SKILL.md); a git URL
-                     works for either — append #<branch-or-tag> to pin
+                     works for either. Append #<commit-sha> to pin exactly (a branch or tag can
+                     move after you review it); installs record the commit they got
 
 Install/update/uninstall targets (pick one):
   (default)          ~/.claude/skills           Claude Code, user scope
@@ -150,29 +153,68 @@ function parseArgs(argv) {
    manifestOf; never touch cat.skillsDir directly (it exists only on the flat skilldrop shape). */
 
 const catalogCache = {};
+/* Commit pinning (RFC-0039, OWASP AST02/AST07). A tag or branch can be moved to point at
+   different code after you reviewed it; a commit SHA cannot. `--from <url>#<sha>` fetches
+   exactly that commit, and every install records the commit it actually got, so the ledger
+   says what is on disk and an unpinned install can tell you how to pin it. */
+const SHA_RE = /^[0-9a-f]{7,40}$/i;
+function gitHead(dir) {
+  try {
+    return execFileSync("git", ["rev-parse", "HEAD"], { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || null;
+  } catch (e) { return null; }
+}
+function splitSource(source) {
+  const i = source.lastIndexOf("#");
+  return i > 0 ? [source.slice(0, i), source.slice(i + 1)] : [source, ""];
+}
+function isPinned(source) { return !!source && SHA_RE.test(splitSource(source)[1]); }
+
+function fetchCatalog(source) {
+  const [url, ref] = splitSource(source);
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "skilldrop-cat-"));
+  const git = (args, cwd) => execFileSync("git", args, { cwd, stdio: ["ignore", "ignore", "pipe"] });
+  try {
+    if (SHA_RE.test(ref)) {
+      // `git clone --branch` takes branches and tags, not commits: fetch the commit itself.
+      git(["init", "-q"], dir);
+      git(["remote", "add", "origin", url], dir);
+      let direct = ref.length === 40;
+      if (direct) {
+        try { git(["fetch", "-q", "--depth", "1", "origin", ref], dir); }
+        catch (e) { direct = false; }  // a host that won't serve a commit by itself
+      }
+      if (!direct) git(["fetch", "-q", "origin", "+refs/heads/*:refs/remotes/origin/*", "+refs/tags/*:refs/tags/*"], dir);
+      try { git(["checkout", "-q", direct ? "FETCH_HEAD" : ref], dir); }
+      catch (e) { die(`catalog '${source}': commit ${ref} isn't in that repository (check the SHA, or that it was pushed)`); }
+    } else {
+      git(["clone", "-q", "--depth", "1", ...(ref ? ["--branch", ref] : []), url, dir]);
+    }
+  } catch (e) {
+    die(`could not fetch catalog '${source}' — not a local path, and git ${SHA_RE.test(ref) ? "could not fetch that commit" : "clone failed"}`);
+  }
+  const head = gitHead(dir);
+  if (SHA_RE.test(ref) && (!head || !head.startsWith(ref.toLowerCase())))
+    die(`catalog '${source}' resolved to ${head || "nothing"}, not the pinned commit ${ref}`);
+  return dir;
+}
+
 function resolveCatalog(source) {
   const key = source || BUNDLED;
   if (catalogCache[key]) return catalogCache[key];
   let dir;
   if (!source) dir = ROOT;
   else if (fs.existsSync(source)) dir = path.resolve(source);
-  else {
-    const [url, ref] = source.split("#");
-    dir = fs.mkdtempSync(path.join(os.tmpdir(), "skilldrop-cat-"));
-    try {
-      execFileSync("git", ["clone", "--depth", "1", ...(ref ? ["--branch", ref] : []), url, dir], { stdio: ["ignore", "ignore", "pipe"] });
-    } catch (e) {
-      die(`could not fetch catalog '${source}' — not a local path, and git clone failed`);
-    }
-  }
+  else dir = fetchCatalog(source);
   const src = source || BUNDLED;
+  // The bundled catalog is versioned by the npm package; anything else by its git commit.
+  const meta = { commit: source ? gitHead(dir) : null, pinned: isPinned(source) };
   const packsDir = path.join(dir, "packs");
   if (fs.existsSync(packsDir) && fs.readdirSync(packsDir).some((p) => fs.existsSync(path.join(packsDir, p, "pack.json"))))
-    return (catalogCache[key] = readPacksCatalog(dir, src));
+    return (catalogCache[key] = Object.assign(readPacksCatalog(dir, src), meta));
   if (fs.existsSync(path.join(dir, "skills")))
-    return (catalogCache[key] = { dir, source: src, shape: "skilldrop", skillsDir: path.join(dir, "skills") });
+    return (catalogCache[key] = Object.assign({ dir, source: src, shape: "skilldrop", skillsDir: path.join(dir, "skills") }, meta));
   if (fs.existsSync(path.join(dir, "packs")))
-    return (catalogCache[key] = readApmCatalog(dir, src));
+    return (catalogCache[key] = Object.assign(readApmCatalog(dir, src), meta));
   die(`'${src}' is not a catalog — expected packs/<pack>/pack.json, a skills/ directory, or packs/<pack>/pack.toml (agentbundle)`);
 }
 
@@ -389,7 +431,7 @@ const SCRIPT_RULES = [
   { id: "shell-exec", sev: "🟧", owasp: ["AST03", "LLM06"], why: "executes shell commands",
     re: /\b(os\.system|subprocess\.(run|call|Popen|check_output)|child_process|execSync|spawnSync|shell_exec|`[^`\n]*\$\()/ },
   { id: "network", sev: "🟧", owasp: ["AST03", "LLM02"], why: "makes outbound network calls",
-    re: /\b(requests\.(get|post|put)|urllib\.request|httpx\.|axios\.|node-fetch|\bfetch\s*\(\s*["'`]https?:|curl\s+https?:|wget\s+https?:)/i },
+    re: /\b(requests\.(get|post|put|patch|delete|head|request|Session)\b|urllib\.request|urlopen\s*\(|http\.client|httpx\.|aiohttp\.|axios\.|node-fetch|\bfetch\s*\(\s*["'`]https?:|curl\s+https?:|wget\s+https?:)/i },
   { id: "credentials", sev: "🟧", owasp: ["AST01", "LLM02"], why: "reads credentials or secret material",
     re: /\b(os\.environ|process\.env)\b[^\n]{0,40}(TOKEN|KEY|SECRET|PASSWORD|CREDENTIAL)|~\/\.(aws|ssh|npmrc|netrc)|\.env\b|id_rsa/i },
   { id: "broad-fs", sev: "🟨", owasp: ["AST03", "LLM06"], why: "writes outside the skill's own directory",
@@ -441,10 +483,47 @@ function scanSkill(cat, s) {
       }
     });
   }
+  findings.push(...permissionGaps(cat, s, findings));
   const order = { "🟥": 0, "🟧": 1, "🟨": 2, "⚪": 3 };
   return findings.sort((a, b) => order[a.sev] - order[b.sev]);
 }
 
+/* RFC-0039: compare what a skill's scripts do (the scan's script findings) with what its
+   manifest says they do. A capability the code shows and the manifest doesn't declare is the
+   finding that matters most: it is either an honest omission or something hiding. */
+function permissionsOf(cat, s) {
+  if (cat.shape === "apm") return null;
+  try { return manifestOf(cat, s).permissions || null; } catch (e) { return null; }
+}
+function permissionGaps(cat, s, findings) {
+  const dir = skillDir(cat, s);
+  if (!dir || !fs.existsSync(path.join(dir, "scripts"))) return [];
+  const perm = permissionsOf(cat, s);
+  if (!perm)
+    return [{ sev: "🟨", id: "no-permissions", owasp: ["AST03", "AST10"], file: "manifest.json", line: 0,
+              why: "ships scripts but declares no permissions (network, commands, files) — nothing to check them against",
+              text: "add a `permissions` block to manifest.json (RFC-0039)" }];
+  const code = findings.filter((f) => SCRIPT_EXT.has(path.extname(f.file).toLowerCase()));
+  const gaps = [];
+  const gap = (id, f, why) => gaps.push({ sev: "🟥", id, owasp: ["AST03", "AST01"], why, file: f.file, line: f.line, text: f.text });
+  for (const f of code) {
+    if ((f.id === "network" || f.id === "exec-remote") && !(perm.network || []).length)
+      gap("undeclared-network", f, "makes network calls, but the manifest declares no network hosts");
+    if ((f.id === "shell-exec" || f.id === "exec-remote") && !(perm.commands || []).length)
+      gap("undeclared-commands", f, "runs commands, but the manifest declares none");
+    if (f.id === "broad-fs" && perm.files !== "anywhere")
+      gap("undeclared-files", f, `writes outside its own paths, but the manifest declares files: "${perm.files}"`);
+  }
+  return gaps;
+}
+function permissionSummary(perm) {
+  if (!perm) return "no permissions declared";
+  const net = (perm.network || []).length ? `contacts ${perm.network.join(", ")}` : "no network";
+  const cmds = (perm.commands || []).length ? `runs ${perm.commands.map((c) => c === "*" ? "commands you configure" : c).join(", ")}` : "runs no commands";
+  const files = { none: "writes nothing", "named-paths": "writes only paths you name", project: "writes inside the project", anywhere: "writes anywhere" }[perm.files] || `files: ${perm.files}`;
+  return `${net} · ${cmds} · ${files}`;
+}
+
 function printScan(cat, names, { compact = false } = {}) {
   let total = 0, worst = null;
   for (const s of names) {
@@ -916,6 +995,7 @@ function copyOne(cat, s, dest, ide, l, notes) {
   const note = writeWiring(ide, dest, s, m.description);
   if (note && notes) notes.push(note);
   l.data[s] = { version: m.version, source: cat.source, files: fileHashes(skillDir(cat, s)) };
+  if (cat.commit) l.data[s].commit = cat.commit;
   return m;
 }
 
@@ -974,6 +1054,7 @@ function mergeOne(cat, s, dest, ide, l, notes, dry = false) {
   const note = writeWiring(ide, dest, s, m.description);
   if (note && notes) notes.push(note);
   l.data[s] = { version: m.version, source: cat.source, files: next };
+  if (cat.commit) l.data[s].commit = cat.commit;
   return { m, kept, orphaned };
 }
 
@@ -1110,10 +1191,20 @@ function install(args) {
     console.log(`\n${withHooks.join(", ")} declare hooks — re-run with --with-hooks to wire them (git pre-commit reminders / session-start context).`);
   }
 
+  if (cat.source !== BUNDLED && cat.commit) {
+    if (cat.pinned) console.log(`\nPinned: these skills came from commit ${cat.commit.slice(0, 12)}, as requested.`);
+    else console.log(`\nNot pinned: '${cat.source}' can change after you review it. These skills came from commit ${cat.commit.slice(0, 12)};` +
+                     `\n  to get exactly these files again, install with --from ${splitSource(cat.source)[0]}#${cat.commit}`);
+  }
   if (cat.source !== BUNDLED) {
     console.log(`\nWARNING: third-party catalog '${cat.source}'. Skills are instructions your AI agent will follow — review each installed SKILL.md under ${dest} before first use. Install copied files only; nothing was executed.`);
     // Supply-chain scan (RFC-0022): surface risky patterns at the moment of trust. Reports only —
     // the files are already copied, and a match is a prompt to read, not a verdict.
+    const scripted = names.filter((s) => fs.existsSync(path.join(skillDir(cat, s), "scripts")));
+    if (scripted.length) {
+      console.log(`\nWhat the scripts declare they do (RFC-0039):`);
+      for (const s of scripted) console.log(`  ${s}: ${permissionSummary(permissionsOf(cat, s))}`);
+    }
     const { total } = printScan(cat, names, { compact: true });
     console.log(total
       ? `\n${total} pattern(s) worth reading before you trust these skills. Full detail: skilldrop scan --from ${cat.source}`
@@ -1159,12 +1250,22 @@ function installedRows(flags) {
   const l = ledger(dest);
   const rows = Object.keys(l.data).sort().map((s) => {
     const src = lsrc(l.data[s]);
-    let current = null, cat = null;
+    let current = null, cat = null, changed = [];
+    const entry = l.data[s];
     try {
       cat = resolveCatalog(src === BUNDLED ? undefined : src);
-      if (skillExists(cat, s)) current = manifestOf(cat, s).version;
+      if (skillExists(cat, s)) {
+        current = manifestOf(cat, s).version;
+        // Same version, different files: the catalog changed the skill without bumping it.
+        // The version check alone would never see that (OWASP AST07, update drift).
+        if (current === lver(entry) && typeof entry === "object" && entry.files) {
+          const now = fileHashes(skillDir(cat, s));
+          changed = [...new Set([...Object.keys(now), ...Object.keys(entry.files)])]
+            .filter((f) => now[f] !== entry.files[f]).sort();
+        }
+      }
     } catch (e) { /* unreachable source: current stays null */ }
-    return { s, src, cat, installed: lver(l.data[s]), current };
+    return { s, src, cat, installed: lver(entry), current, changed, pinned: isPinned(src) };
   });
   return { dest, ide, l, rows };
 }
@@ -1173,7 +1274,10 @@ function update(args) {
   const { dest, ide, l, rows } = installedRows(args.flags);
   if (!rows.length) return console.log(`nothing installed at ${dest}`);
   const dry = !!args.flags["dry-run"];
-  const due = rows.filter((r) => r.current && r.current !== r.installed);
+  // A row is due when its version moved, or (with --changed) when its files moved under the
+  // same version. Same-version changes are never taken silently: they are named and skipped.
+  const isDue = (r) => r.current && (r.current !== r.installed || (args.flags.changed && r.changed.length));
+  const due = rows.filter(isDue);
   if (args.flags.force && !dry) {
     const lost = due.flatMap((r) => editedFiles(dest, r.s, l.data[r.s]).map((f) => `${r.s}/${f}`));
     if (lost.length) {
@@ -1183,19 +1287,20 @@ function update(args) {
   }
   if (dry) return planUpdate(dest, ide, l, rows, args.flags);
   let n = 0, conflicts = 0;
+  const silent = rows.filter((r) => r.current === r.installed && r.changed.length && !args.flags.changed);
   for (const r of rows) {
     if (!r.current) { console.log(`skip ${r.s}: source '${r.src}' unreachable or skill gone from it`); continue; }
-    if (r.current === r.installed) continue;
+    if (!isDue(r)) continue;
     const problems = checkSkill(r.cat, r.s);
     if (problems.length) { console.log(`skip ${r.s}: fails structural check in '${r.src}' (${problems[0]})`); continue; }
     // No baseline (installed before RFC-0032) or --force: overwrite as before, and record one.
     const entry = l.data[r.s];
     if (args.flags.force || typeof entry !== "object" || !entry.files) {
       copyOne(r.cat, r.s, dest, ide, l);
-      console.log(`updated ${r.s} ${r.installed} -> ${r.current} (${r.src})`);
+      console.log(`updated ${r.s} ${r.installed === r.current ? `${r.current} (same version, changed upstream)` : `${r.installed} -> ${r.current}`} (${r.src})`);
     } else {
       const { kept, orphaned } = mergeOne(r.cat, r.s, dest, ide, l);
-      console.log(`updated ${r.s} ${r.installed} -> ${r.current} (${r.src})`);
+      console.log(`updated ${r.s} ${r.installed === r.current ? `${r.current} (same version, changed upstream)` : `${r.installed} -> ${r.current}`} (${r.src})`);
       for (const f of kept) console.log(`  kept your edits in ${f} — new version at ${f}.upstream`);
       for (const f of orphaned) console.log(`  kept ${f} — dropped upstream, but you edited it`);
       conflicts += kept.length;
@@ -1203,10 +1308,17 @@ function update(args) {
     n++;
   }
   saveLedger(l);
-  console.log(n ? `\n${n} skill(s) updated.` : "everything up to date.");
+  console.log(n ? `\n${n} skill(s) updated.` : (silent.length ? "no version changes." : "everything up to date."));
+  if (silent.length)
+    console.log(`\nNot taken: ${silent.map((r) => r.s).join(", ")} changed upstream without a version bump.` +
+                `\n  Read the change (skilldrop diff <skill>), then take it with: skilldrop update --changed`);
+  const pinned = rows.filter((r) => r.pinned);
+  if (pinned.length)
+    console.log(`\n${pinned.length} skill(s) come from a catalog pinned to a commit, so they stay as they are. To move them,` +
+                `\n  reinstall with the new commit: skilldrop install <skill> --from <url>#<new-commit>`);
   // An update is a fresh act of trust in a third-party catalog (OWASP AST07): scan what changed.
   const thirdParty = {};
-  for (const r of rows) if (r.current && r.current !== r.installed && r.src !== BUNDLED) (thirdParty[r.src] = thirdParty[r.src] || { cat: r.cat, names: [] }).names.push(r.s);
+  for (const r of rows) if (isDue(r) && r.src !== BUNDLED) (thirdParty[r.src] = thirdParty[r.src] || { cat: r.cat, names: [] }).names.push(r.s);
   for (const { cat, names } of Object.values(thirdParty)) {
     const { total } = printScan(cat, names, { compact: true });
     console.log(total ? `\n${total} pattern(s) in the updated skills from '${cat.source}' worth reading. Full detail: skilldrop scan --from ${cat.source}`
@@ -1222,7 +1334,11 @@ function planUpdate(dest, ide, l, rows, flags) {
   let n = 0;
   for (const r of rows) {
     if (!r.current) { console.log(`would skip ${r.s}: source '${r.src}' unreachable or skill gone from it`); continue; }
-    if (r.current === r.installed) continue;
+    if (r.current === r.installed && !r.changed.length) continue;
+    if (r.current === r.installed && !flags.changed) {
+      console.log(`would not take ${r.s}: ${r.changed.length} file(s) changed upstream without a version bump (add --changed to take them)`);
+      continue;
+    }
     const problems = checkSkill(r.cat, r.s);
     if (problems.length) { console.log(`would skip ${r.s}: fails structural check (${problems[0]})`); continue; }
     n++;
@@ -1237,25 +1353,34 @@ function planUpdate(dest, ide, l, rows, flags) {
     for (const f of kept) console.log(`  would keep your edits in ${f} and write the new version to ${f}.upstream`);
     for (const f of orphaned) console.log(`  would keep ${f} — dropped upstream, but you edited it`);
   }
-  console.log(n ? `\n${n} skill(s) would update. Rerun without --dry-run to apply.` : "everything up to date.");
+  const held = rows.filter((r) => r.current && r.current === r.installed && r.changed.length && !flags.changed).length;
+  console.log(n ? `\n${n} skill(s) would update. Rerun without --dry-run to apply.` : (held ? "no version changes." : "everything up to date."));
 }
 
 function outdated(args) {
   const { dest, rows } = installedRows(args.flags);
   const stale = rows.filter((r) => r.current && r.current !== r.installed);
+  const drift = rows.filter((r) => r.changed && r.changed.length);
   if (args.flags.json)
     return emitJSON({
       dest,
       count: rows.length,
       outdatedCount: stale.length,
+      changedWithoutVersionCount: drift.length,
       skills: rows.map((r) => ({
         name: r.s, installed: r.installed, current: r.current,
         source: r.src, outdated: !!(r.current && r.current !== r.installed),
+        changedWithoutVersion: r.changed || [], pinned: r.pinned,
       })),
     });
   if (!rows.length) return console.log(`nothing installed at ${dest}`);
   for (const r of stale) console.log(`${r.s}: installed ${r.installed}, current ${r.current} (${r.src})`);
-  console.log(stale.length ? `\n${stale.length} outdated — run: skilldrop update` : "everything up to date.");
+  for (const r of drift)
+    console.log(`${r.s}: ${r.changed.length} file(s) changed in '${r.src}' without a version bump (${r.changed.slice(0, 3).join(", ")}${r.changed.length > 3 ? ", …" : ""})`);
+  if (drift.length)
+    console.log(`\n${drift.length} skill(s) changed upstream with the same version. Read the change first (skilldrop diff <skill>),` +
+                `\nthen take it with: skilldrop update --changed`);
+  console.log(stale.length ? `\n${stale.length} outdated — run: skilldrop update` : (drift.length ? "" : "everything up to date."));
 }
 
 function uninstall(args) {
@@ -1890,6 +2015,7 @@ function info(args) {
       deps: { pip: (m.deps || {}).pip || [], npm: (m.deps || {}).npm || [], requirementsTxt: needsPip },
       env: { required: (m.env || {}).required || [], optional: (m.env || {}).optional || [] },
       hooks: m.hooks || [],
+      permissions: m.permissions || null,
     });
   console.log(`${m.name}@${m.version}  (tier: ${(m.model && m.model.tier) || "n/a"})\n\n${m.description}\n`);
   console.log(`catalog: ${cat.source}`);
@@ -1898,6 +2024,8 @@ function info(args) {
   if (((m.deps || {}).pip || []).length || fs.existsSync(path.join(skillDir(cat, s), "requirements.txt")))
     console.log("deps:    python (requirements.txt)");
   if (((m.env || {}).required || []).length) console.log(`env:     ${m.env.required.join(", ")} (required)`);
+  if (fs.existsSync(path.join(skillDir(cat, s), "scripts")))
+    console.log(`scripts: ${permissionSummary(m.permissions)}${m.permissions && m.permissions.notes ? `\n         ${m.permissions.notes}` : ""}`);
 }
 
 function listPacks(args) {
@@ -1924,6 +2052,8 @@ function validateCmd(args) {
   let bad = 0;
   for (const s of names) {
     const problems = checkSkill(cat, s);
+    for (const f of scanSkill(cat, s).filter((x) => x.id.startsWith("undeclared-")))
+      problems.push(`${f.file}:${f.line} ${f.why} (RFC-0039)`);
     for (const p of problems) console.log(`FAIL ${s}: ${p}`);
     if (problems.length) bad++;
   }

package/contracts/skill.schema.json

@@ -38,6 +38,21 @@
                       "description": "Vars that change behaviour but do not block." }
       }
     },
+    "permissions": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["network", "commands", "files"],
+      "description": "RFC-0039 (OWASP AST03, AST10). What the skill's scripts do, declared so a reader and `skilldrop scan` can compare it with what the code does. Required for every skill that ships scripts/.",
+      "properties": {
+        "network": { "type": "array", "items": { "type": "string" },
+                     "description": "Hosts the scripts contact, e.g. api.figma.com. Empty means none." },
+        "commands": { "type": "array", "items": { "type": "string" },
+                      "description": "External programs the scripts run, e.g. pdftotext. \"*\" means commands the user configures. Empty means none." },
+        "files": { "type": "string", "enum": ["none", "named-paths", "project", "anywhere"],
+                   "description": "What the scripts write: nothing; only paths the user names; inside the current project; or anywhere." },
+        "notes": { "type": "string", "description": "Anything a reviewer should know that the fields can't say." }
+      }
+    },
     "related": {
       "type": "array",
       "items": { "type": "string" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skilldrop-cli",
-  "version": "0.15.1",
+  "version": "0.16.1",
   "description": "Portable AI-agent skills for the deliverables knowledge workers ship \u2014 diagrams, ADRs, PRDs, runbooks, decks, reviews \u2014 installable into Claude Code, Cursor, Kiro, and any IDE that takes custom instructions. One command per skill or per role-based pack.",
   "author": {
     "name": "Sanjay Ananthanarayan",

package/packs/ai-engineering/skills/ai-usage-report/manifest.json

@@ -7,5 +7,6 @@
   "env": { "required": [], "optional": [] },
   "related": [],
   "tags": ["ai-usage", "reporting", "telemetry", "adoption", "observability", "manager-tools"],
+  "permissions": {"network": [], "commands": [], "files": "named-paths"},
   "model": { "tier": "standard", "rationale": "Tabulates telemetry; the 'AI theater' effectiveness call needs some judgment." }
 }

package/packs/converters/skills/file-to-markdown/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "file-to-markdown",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Convert a Word document, PowerPoint deck, Excel workbook, web page, CSV, JSON, text file or PDF into clean Markdown that keeps headings, lists, tables, links, bold and italic, slide titles and speaker notes, and reports everything it dropped (images, charts, comments, formulas, tracked changes), so the content can be read, reviewed or fed to another skill. Use when the user hands over a .docx, .pptx, .xlsx, .html, .csv, .json or .pdf and says \"read this\", \"turn this into markdown\", \"extract the text\", or wants it critiqued or briefed.",
   "entrypoint": "SKILL.md",
   "deps": {
@@ -41,6 +41,7 @@
     "pdf",
     "extract"
   ],
+  "permissions": {"network": [], "commands": ["pdftotext"], "files": "named-paths", "notes": "pdftotext (Poppler) is used only for .pdf input, and only if it is installed."},
   "model": {
     "tier": "light",
     "rationale": "A deterministic stdlib script does the extraction; the model runs it, relays the dropped-content report and hands off. No generation beyond a short summary of losses."

package/packs/converters/skills/file-to-markdown/scripts/to_markdown.py

@@ -56,6 +56,7 @@ class Report:
 def md_escape(text):
     text = text.replace("\\", "\\\\")
     text = re.sub(r"([*_`\[\]])", r"\\\1", text)
+    text = re.sub(r"<(?=[A-Za-z/!])", r"\\<", text)  # literal <tag> text must not read as raw HTML
     return text
 
 
@@ -330,7 +331,7 @@ def docx_to_md(path, rep):
                 if tcpr is not None and tcpr.find(W + "gridSpan") is not None:
                     row.extend([""] * (int(tcpr.find(W + "gridSpan").get(W + "val", "1")) - 1))
             rows.append(row)
-        if any(tbl.iter(W + "tbl")) and len(list(tbl.iter(W + "tbl"))) > 1:
+        if len(list(tbl.iter(W + "tbl"))) > 1:
             rep.notes.append("a nested table was flattened into its parent cell")
         rep.keep("tables")
         return md_table(rows)
@@ -339,6 +340,19 @@ def docx_to_md(path, rep):
         return "".join((n.text or "") if n.tag == W + "t" else "\t" for n in p.iter()
                        if n.tag in (W + "t", W + "tab"))
 
+    def style_name(p):
+        ppr = p.find(W + "pPr")
+        ps = ppr.find(W + "pStyle") if ppr is not None else None
+        if ps is None:
+            return ""
+        sid = ps.get(W + "val", "")
+        return styles.get(sid, (sid.lower(), None))[0]
+
+    def code_text(p):
+        """Text of a code paragraph: line breaks and tabs kept, no inline formatting or escaping."""
+        return "".join((n.text or "") if n.tag == W + "t" else "\t" if n.tag == W + "tab" else "\n"
+                       for n in p.iter() if n.tag in (W + "t", W + "tab", W + "br", W + "cr"))
+
     def run_size(p):
         """(largest font size in half-points, every text run bold?) for unstyled documents."""
         sizes, bold = [0], True
@@ -402,7 +416,19 @@ def docx_to_md(path, rep):
             if not text:
                 prev_list = False if not li else prev_list
                 continue
-            if lvl:
+            sname = "" if lvl or li else style_name(el)
+            if re.match(r"(source ?code|code|html preformatted|preformatted text|macro text)$", sname):
+                # one code block may be one paragraph with line breaks or a run of one-line paragraphs
+                if blocks and blocks[-1][0] == "code":
+                    blocks[-1] = ("code", blocks[-1][1] + "\n" + code_text(el))
+                else:
+                    blocks.append(("code", code_text(el)))
+                    rep.keep("code blocks")
+                prev_list = False
+            elif "quote" in sname or sname == "block text":
+                blocks.append(("block", "> " + text.replace("\n", "\n> ")))
+                prev_list = False
+            elif lvl:
                 rep.keep("headings")
                 blocks.append(("block", "#" * lvl + " " + text.replace("  \n", " ")))
                 prev_list = False
@@ -439,6 +465,11 @@ def docx_to_md(path, rep):
     for k, (kind, text) in enumerate(blocks):
         if k and not (kind == "list" and blocks[k - 1][0] == "list"):
             out.append("")
+        if kind == "code":
+            fence = "```"
+            while fence in text:
+                fence += "`"
+            text = fence + "\n" + text + "\n" + fence
         out.append(text)
     return "\n".join(out) + "\n"
 

package/packs/converters/skills/md-to-docx/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "md-to-docx",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Turn a Markdown draft into a Word document (.docx) that someone outside engineering can open, edit and track changes in, with real Heading styles so the navigation pane and table of contents work, live hyperlinks, numbered and bulleted lists, tables, code blocks, embedded images and optional brand fonts and colours, and a warning for everything that could not be carried over. Use when the user wants a Markdown file as a Word doc, says \"send this as a .docx\", \"convert to Word\", \"legal needs it in Word\", or \"make this editable for the client\".",
   "entrypoint": "SKILL.md",
   "deps": {
@@ -44,6 +44,7 @@
     "document",
     "export"
   ],
+  "permissions": {"network": [], "commands": [], "files": "named-paths"},
   "model": {
     "tier": "standard",
     "rationale": "A stdlib script does the conversion; the model restructures the Markdown so it converts cleanly (heading levels, footnotes, HTML), reads each warning and explains the losses. Bounded editing, no open-ended generation."

package/packs/converters/skills/md-to-docx/scripts/md_to_docx.py

@@ -34,6 +34,8 @@ WARNINGS = []
 
 def warn(line, msg):
     where = "line %d: " % line if line else ""
+    if where + msg in WARNINGS:  # a big table repeats one warning per cell; say it once
+        return
     WARNINGS.append(where + msg)
     print("WARN %s%s" % (where, msg), file=sys.stderr)
 
@@ -942,7 +944,7 @@ class Doc(object):
 
 
 def static_parts(title):
-    now = datetime.datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%SZ")
+    now = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
     ct = ('<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n'
           '<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">'
           '<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>'

package/packs/converters/skills/md-to-html/manifest.json

@@ -35,6 +35,7 @@
     "export",
     "brand"
   ],
+  "permissions": {"network": [], "commands": [], "files": "named-paths", "notes": "The script makes no network calls. With --mermaid cdn, the HTML it writes loads Mermaid from cdn.jsdelivr.net when someone opens it."},
   "model": {
     "tier": "light",
     "rationale": "A deterministic stdlib script does the conversion; the model picks options, fixes a few unsupported Markdown constructs and relays the script's warnings. Little judgment."

package/packs/converters/skills/md-to-xlsx/SKILL.md

@@ -78,7 +78,8 @@ nothing. Formulas stay off unless the request says otherwise, noted as an `[assu
 | Anything else, including `n/a`, `1.234,50`, `30/09/2026` | Text |
 
 In Markdown cells, `**bold**`, `` `code` ``, links and images are reduced to their text, and
-`<br>` becomes a line break inside a wrapped cell. JSON numbers and booleans keep their type.
+`<br>` becomes a line break inside a wrapped cell. JSON numbers and booleans keep their type,
+except integers over 15 digits, which become text.
 JSON strings stay text except ISO dates, because whoever produced the JSON chose a string.
 
 ## Useful references in this skill

package/packs/converters/skills/md-to-xlsx/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "md-to-xlsx",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Turn the tables in a Markdown file, a CSV or a JSON array into an Excel workbook (.xlsx) that finance, ops or a client can sort, filter and sum, with one sheet per table named from its heading, real numbers, percentages, currency and dates instead of text, a bold frozen header row with filters, sensible column widths, and formulas left inert unless asked for. Use when the user wants a spreadsheet from Markdown tables or data, says \"put this in Excel\", \"convert the CSV to xlsx\", \"give finance a spreadsheet\", or \"turn this JSON into a sheet\".",
   "entrypoint": "SKILL.md",
   "deps": {
@@ -25,6 +25,7 @@
     "markdown",
     "convert"
   ],
+  "permissions": {"network": [], "commands": [], "files": "named-paths"},
   "model": {
     "tier": "standard",
     "rationale": "A stdlib script types and writes the cells; the model shapes tables from the source (headings, units, one header row), decides whether formulas are safe to enable, and checks the per-sheet type counts against the data. Bounded, mostly mechanical judgment."

package/packs/converters/skills/md-to-xlsx/scripts/md_to_xlsx.py

@@ -170,8 +170,11 @@ def type_text(s, formulas, stats, tz_flag, infer_numbers=True):
                         text = "0"
                     return Cell("n", text, fmt, width)
         if RE_SCI.match(s):
-            stats["numbers"] += 1
-            return Cell("n", repr(float(s)), None, width)
+            val = float(s)
+            # 1e999 overflows to inf, which is not a number Excel can read: keep it as text
+            if val == val and val not in (float("inf"), float("-inf")):
+                stats["numbers"] += 1
+                return Cell("n", num_text(val), None, width)
     if len(raw) > MAX_CELL:
         stats["truncated"] += 1
         s = s[:MAX_CELL]
@@ -189,6 +192,10 @@ def type_json(v, formulas, stats, tz_flag):
         if v != v or v in (float("inf"), float("-inf")):
             stats["text"] += 1
             return Cell("s", str(v), None, len(str(v)))
+        if isinstance(v, int) and len(str(abs(v))) > 15:
+            # Excel keeps 15 significant digits; a longer integer is an ID, and rounding it is data loss
+            stats["text"] += 1
+            return Cell("s", str(v), None, len(str(v)))
         stats["numbers"] += 1
         return Cell("n", num_text(v), None, len(num_text(v)))
     if isinstance(v, (dict, list)):
@@ -230,6 +237,9 @@ def split_row(line):
     return cells
 
 
+HTML_TAGS = [0]  # tags removed by strip_md, reported once per file
+
+
 def strip_md(s):
     """Plain text from a Markdown table cell."""
     s = re.sub(r"<br\s*/?>", "\n", s, flags=re.I)
@@ -240,7 +250,8 @@ def strip_md(s):
     s = re.sub(r"(?<![\w*])\*(?!\s)(.+?)(?<!\s)\*(?![\w*])", r"\1", s)
     s = re.sub(r"(?<!\w)_(?!\s)(.+?)(?<!\s)_(?!\w)", r"\1", s)
     s = re.sub(r"~~(.+?)~~", r"\1", s)
-    s = re.sub(r"</?[A-Za-z][^>]*>", "", s)
+    s, n = re.subn(r"</?[A-Za-z][^>]*>", "", s)
+    HTML_TAGS[0] += n
     s = re.sub(r"\\([\\`*_{}\[\]()#+\-.!|~])", r"\1", s)
     return s
 
@@ -280,6 +291,9 @@ def read_markdown(text):
             tables.append((heading, header, rows, start))
             continue
         i += 1
+    if HTML_TAGS[0]:
+        warn("%d HTML tag(s) removed from headings and cells (text between them kept); write a literal "
+             "<...> as &lt;...&gt; or in backticks to keep it" % HTML_TAGS[0])
     return tables
 
 
@@ -533,7 +547,7 @@ def write_xlsx(out, sheets, title, formulas):
                 '<bookViews><workbookView activeTab="0"/></bookViews><sheets>%s</sheets>'
                 '<definedNames>%s</definedNames>%s</workbook>') % (
                     "".join(sheet_tags), "".join(names), '<calcPr fullCalcOnLoad="1"/>' if formulas else "")
-    now = datetime.datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%SZ")
+    now = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
     core = ('<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n'
             '<cp:coreProperties xmlns:cp="http://schemas.openxmlformats.org/package/2006/metadata/core-properties" '
             'xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" '

package/packs/converters/skills/mermaid-render/manifest.json

@@ -32,6 +32,7 @@
     "png",
     "render"
   ],
+  "permissions": {"network": [], "commands": ["mmdc"], "files": "named-paths", "notes": "mmdc (mermaid-cli) renders SVG, PNG and PDF if it is installed. Without it the script writes an HTML page that loads Mermaid from cdn.jsdelivr.net when opened; the script itself makes no network calls."},
   "model": {
     "tier": "standard",
     "rationale": "The script lints and renders deterministically, but fixing a broken diagram means reading the author's intent and rewriting syntax without changing nodes, edges or labels, and knowing when to ask instead."

package/packs/core/skills/output-hygiene/manifest.json

@@ -26,6 +26,7 @@
     "ai-detection",
     "pre-ship"
   ],
+  "permissions": {"network": [], "commands": [], "files": "named-paths", "notes": "Writes only with --fix, which rewrites the files it was given, in place."},
   "model": {
     "tier": "standard",
     "rationale": "The mechanical pass is a deterministic script; the model does bounded rewriting of flagged prose against a fixed tell list, not adversarial review."

package/packs/data-analytics/skills/sql-review/manifest.json

@@ -34,6 +34,7 @@
     "bigquery",
     "snowflake"
   ],
+  "permissions": {"network": [], "commands": [], "files": "named-paths"},
   "model": {
     "tier": "heavy",
     "rationale": "Adversarial correctness review: finding join fan-out, NULL and timezone bugs means reasoning about data the query never shows, and a missed finding ships a wrong number. Never downgrade."

package/packs/design/skills/brand-kit/manifest.json

@@ -37,6 +37,7 @@
     "design",
     "style-guide"
   ],
+  "permissions": {"network": [], "commands": [], "files": "none", "notes": "The checker reads brand.json and the files it names, and writes nothing."},
   "model": {
     "tier": "standard",
     "rationale": "Extracts and normalises brand facts from files and pages, then runs a checker. Bounded synthesis."

package/packs/design/skills/deck-builder/manifest.json

@@ -13,5 +13,6 @@
     "pip": "python3 -m pip install -r requirements.txt"
   },
   "tags": ["powerpoint", "pptx", "deck", "presentation", "template", "charts", "stakeholder-communication"],
+  "permissions": {"network": [], "commands": [], "files": "named-paths", "notes": "Needs the python-pptx package (declared in deps)."},
   "model": { "tier": "standard", "rationale": "Shapes content, maps a brand template's layouts, and runs a script. Judgment, not hard reasoning." }
 }

package/packs/design/skills/marketing-flyer/manifest.json

@@ -32,6 +32,7 @@
     "brand",
     "design"
   ],
+  "permissions": {"network": [], "commands": ["google-chrome", "chromium", "chrome"], "files": "named-paths", "notes": "A local Chrome or Chromium is run headless only for --pdf and --png; the HTML needs nothing."},
   "model": {
     "tier": "standard",
     "rationale": "Writes short copy to fit and fills a spec for a deterministic builder. Bounded generation."

package/packs/dev-team/skills/contribution-wizard/SKILL.md

@@ -46,6 +46,8 @@ After intake, produce the following in a single response, each in its own fenced
 }
 ```
 
+If the skill ships `scripts/`, add a `permissions` block before `model`: the hosts the scripts contact, the external programs they run, and where they write (`"none"`, `"named-paths"`, `"project"` or `"anywhere"`). For example: `"permissions": { "network": [], "commands": ["pdftotext"], "files": "named-paths" }`. Validation fails a script skill without it, and fails one whose code does something it doesn't declare.
+
 Tier guidance:
 - **light**: pattern matching, formatting, extraction with no judgment calls
 - **standard**: synthesis, judgment calls, structured output requiring reasoning (most skills)

package/packs/dev-team/skills/contribution-wizard/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "contribution-wizard",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Guides an author through creating a new skilldrop skill from scratch — generates the manifest, SKILL.md, eval cases, and skill-catalogue entry from a plain-language description of the skill's purpose. Use when authoring a new skill for this repo or a private fork, ensuring a new skill meets the schema and validation requirements before submission.",
   "entrypoint": "SKILL.md",
   "deps": { "npm": [], "pip": [] },

package/packs/dev-team/skills/pre-merge-review/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "pre-merge-review",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Gate an existing change for merge — run one skill that fires the whole production-readiness pass. First a deterministic mechanical gate (lint + typecheck + tests, via a script whose exit code decides), then the three-reviewer panel dispatched in parallel — devils-advocate (correctness), security-reviewer (exploitability), code-quality (craft) — then a single READY / NOT READY verdict. Use before opening a PR or merging, when you want the full review fleet run on a diff you already have. Do NOT use to implement a feature from a spec (that's feature-implement-loop) or to review a document (that's doc-critique).",
   "entrypoint": "SKILL.md",
   "deps": { "npm": [], "pip": [] },
@@ -10,5 +10,6 @@
     { "to": "council-review", "when": "the blocker is a design disagreement, not a defect", "purpose": "Adjudicate the disagreement outside the diff.", "fallback": "If council-review is absent, state each position and its strongest counter inline, and name the crux the decision turns on." }
   ],
   "tags": ["dev-workflow", "code-review", "pre-merge", "quality-gate", "subagents", "production-readiness"],
+  "permissions": {"network": [], "commands": ["git", "ruff", "mypy", "pytest", "*"], "files": "project", "notes": "Runs the lint, typecheck and test commands configured for the project, through a shell, by design. --install-hook writes a git pre-commit hook in the repository."},
   "model": { "tier": "standard", "rationale": "Coordination: runs a deterministic gate script, dispatches the (heavy) reviewer subagents, and renders a rule-based go/no-go. The adversarial reasoning is delegated to the panel, so the skill itself is orchestration, not deep judgment." }
 }

package/packs/dev-team/skills/pre-merge-review/scripts/gate.py

@@ -112,7 +112,10 @@ def install_hook(root, cmd, config):
     body += "\n" + _hook_block(cmd, config)
     with open(path, "w", encoding="utf-8") as fh:
         fh.write(body)
-    os.chmod(path, 0o755)
+    # chmod +x, not a fixed 0o755: add execute only where the umask already granted read, so a
+    # restrictive umask (077) keeps the hook private instead of being widened to world-readable.
+    mode = os.stat(path).st_mode
+    os.chmod(path, mode | ((mode & 0o444) >> 2))
     print(f"gate: installed a blocking pre-commit hook -> {path}")
     print("      a RED gate now blocks `git commit` (any tool). Bypass once with --no-verify; "
           "wire CI required-checks for the un-bypassable backstop.")

package/packs/experience-design/skills/content-design/manifest.json

@@ -33,6 +33,7 @@
     "ux",
     "user-needs"
   ],
+  "permissions": {"network": [], "commands": [], "files": "none", "notes": "Prints readability figures; writes nothing."},
   "model": {
     "tier": "standard",
     "rationale": "Rewrites source text from user needs under fixed plain-language rules, with a script for the readability numbers. Prioritising questions needs judgment, but facts come from the source."

package/packs/grc/skills/risk-register/manifest.json

@@ -35,6 +35,7 @@
     "governance",
     "compliance"
   ],
+  "permissions": {"network": [], "commands": [], "files": "named-paths"},
   "model": {
     "tier": "standard",
     "rationale": "Structured writing against a fixed format and scale, with a script doing the checks and counts. Scoring needs some judgment but is bounded by the written scale."

package/packs/infra-as-code/skills/terraform-plan-review/manifest.json

@@ -40,6 +40,7 @@
     "iam",
     "drift"
   ],
+  "permissions": {"network": [], "commands": [], "files": "named-paths", "notes": "Reads a plan JSON, which can hold secrets in clear text; the script never prints attribute values."},
   "model": {
     "tier": "heavy",
     "rationale": "Adversarial review of a destructive change: judging which replacements lose data, which access changes widen exposure, and what is out of scope needs careful reasoning; a missed destroy costs far more than the model."

package/packs/research/skills/hypothesis-comparison/manifest.json

@@ -35,6 +35,7 @@
     "analysis",
     "evidence"
   ],
+  "permissions": {"network": [], "commands": [], "files": "named-paths"},
   "model": {
     "tier": "heavy",
     "rationale": "Judgment-heavy: generating real rivals, rating every evidence-hypothesis cell honestly and resisting the favourite theory is where a fast pass fails; the script only does the arithmetic."

package/packs/research/skills/source-synthesis/manifest.json

@@ -34,6 +34,7 @@
     "citations",
     "evidence"
   ],
+  "permissions": {"network": [], "commands": [], "files": "named-paths"},
   "model": {
     "tier": "standard",
     "rationale": "Bounded synthesis over supplied text with a fixed citation format and strength criteria; the citation checker catches the mechanical failures, so mid-tier judgment is enough."

package/packs/skill-engineering/skills/skill-review/manifest.json

@@ -42,6 +42,7 @@
     "security",
     "owasp"
   ],
+  "permissions": {"network": [], "commands": [], "files": "named-paths"},
   "model": {
     "tier": "heavy",
     "rationale": "Adversarial audit with a verdict: routing collisions and paraphrased safety issues are what a fast pass misses, and the lint script covers only the mechanical half."

package/packs/solution-architect/skills/figma-diagrams/manifest.json

@@ -28,6 +28,7 @@
     "design",
     "api"
   ],
+  "permissions": {"network": ["api.figma.com"], "commands": [], "files": "named-paths", "notes": "Reads FIGMA_TOKEN from the environment to call the Figma REST API."},
   "model": {
     "tier": "standard",
     "rationale": "API calls + spec generation. Bounded transformation."

package/packs/sre-oncall/skills/cloud-cost-review/manifest.json

@@ -41,6 +41,7 @@
     "savings",
     "sre"
   ],
+  "permissions": {"network": [], "commands": [], "files": "named-paths"},
   "model": {
     "tier": "standard",
     "rationale": "A stdlib script does the aggregation; the model maps columns, checks evidence and computes savings with shown arithmetic against a fixed category checklist, which is bounded judgment."

package/packs/sre-oncall/skills/delivery-metrics-report/manifest.json

@@ -40,6 +40,7 @@
     "engineering-metrics",
     "reporting"
   ],
+  "permissions": {"network": [], "commands": [], "files": "named-paths"},
   "model": {
     "tier": "standard",
     "rationale": "A stdlib script computes every number; the model maps columns, checks data quality and interprets weekly trends against fixed DORA definitions, which is bounded judgment."

package/packs/trackers/skills/backlog-triage/manifest.json

@@ -34,6 +34,7 @@
     "refinement",
     "duplicates"
   ],
+  "permissions": {"network": [], "commands": [], "files": "named-paths"},
   "model": {
     "tier": "standard",
     "rationale": "A script does the counting; the model confirms duplicates by reading, judges readiness and writes a reasoned ordering. Bounded judgment over structured data."

package/packs/trackers/skills/team-status-report/manifest.json

@@ -25,6 +25,7 @@
     "rag",
     "stakeholder-update"
   ],
+  "permissions": {"network": [], "commands": [], "files": "named-paths"},
   "model": {
     "tier": "standard",
     "rationale": "A script computes every count and the suggested RAG; the model writes plain-language summaries, attributes outside facts and frames risks and asks. Bounded writing over computed numbers."

package/packs/trackers/skills/tracker-brief-sync/manifest.json

@@ -33,6 +33,7 @@
     "traceability",
     "drift"
   ],
+  "permissions": {"network": [], "commands": [], "files": "named-paths", "notes": "The github target writes a shell script of gh commands for the user to run; it runs nothing itself."},
   "model": {
     "tier": "standard",
     "rationale": "Maps doc sections to items and writes acceptance criteria that restate requirements; a script checks the spec, writes the import file and computes drift. Bounded transformation with a deterministic check."