harnessed 3.5.0 → 3.6.0

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,34 @@
+# Third-Party Notices
+
+`harnessed` itself is licensed under the Apache License 2.0 (see `LICENSE` and
+`NOTICE` at the repo root). This file enumerates third-party material whose
+text — verbatim or paraphrased — is incorporated into shipped harnessed source
+files. Upstream attributions for each capability *manifest* (and its installed
+side effects on the user's machine) continue to be tracked separately in
+`NOTICES.md` (auto-populated by `harnessed install` from each manifest's
+`metadata.upstream.notice` field).
+
+---
+
+## mattpocock/skills
+
+- **Source**: https://github.com/mattpocock/skills
+- **Commit SHA pinned**: `b8be62ffacb0118fa3eaa29a0923c87c8c11985c`
+- **License**: MIT
+- **Used in**: `workflows/role-prompts.yaml` — paraphrased methodology
+  excerpts inlined into the `task-clarify`, `task-code`, and `discuss-subtask`
+  sub-workflow role-prompt entries (introduced in v3.6.0 Phase 1). Each
+  paraphrased block carries an inline attribution comment naming the source
+  SKILL.md path and the pinned commit SHA.
+- **Excerpts paraphrased (not redistributed verbatim)**:
+  - `skills/engineering/grill-with-docs/SKILL.md` → `task-clarify.responsibility` + checklist
+  - `skills/engineering/zoom-out/SKILL.md` → `task-code.checklist`
+  - `skills/engineering/improve-codebase-architecture/SKILL.md` → `task-code.checklist`
+  - `skills/productivity/grill-me/SKILL.md` → `discuss-subtask.responsibility` + checklist
+- **Full upstream license text**: preserved at
+  `.planning/v3.6.0/mattpocock-source/LICENSE` (not shipped in the npm
+  tarball; retained for audit + license-compliance evidence). The SHA
+  metadata + re-fetch instructions live in
+  `.planning/v3.6.0/mattpocock-source/SHA.txt`.
+- **Scope of redistribution**: only the paraphrased excerpts above are
+  redistributed (no verbatim SKILL.md content ships in the npm tarball).

package/dist/cli.mjs

@@ -621,6 +621,105 @@ var init_check_planning_with_files = __esm({
     REMEDIATION = "install via Claude Code plugin marketplace: `claude plugin install planning-with-files` (requires >=2.2.0 per R20.15 + D-15)";
   }
 });
+
+// src/cli/lib/check-mattpocock-skills.ts
+var check_mattpocock_skills_exports = {};
+__export(check_mattpocock_skills_exports, {
+  checkMattpocockSkills: () => checkMattpocockSkills
+});
+async function checkMattpocockSkills() {
+  const pluginRoot = join(
+    homedir(),
+    ".claude",
+    "plugins",
+    "cache",
+    "mattpocock-skills",
+    "mattpocock-skills"
+  );
+  const skillRoot = join(homedir(), ".claude", "skills", "mattpocock-skills");
+  try {
+    const entries = await readdir(pluginRoot);
+    const versions = entries.filter((e) => /^\d+\.\d+/.test(e));
+    if (versions.length > 0) {
+      return {
+        name: "mattpocock-skills",
+        status: "pass",
+        message: `installed as plugin (version ${versions.join(", ")})`
+      };
+    }
+  } catch {
+  }
+  try {
+    await stat(skillRoot);
+    return {
+      name: "mattpocock-skills",
+      status: "pass",
+      message: `installed as user-skill (${skillRoot})`
+    };
+  } catch {
+  }
+  return {
+    name: "mattpocock-skills",
+    status: "warn",
+    message: "not installed (plugin cache + user-skill paths both missing)",
+    fix: REMEDIATION2
+  };
+}
+var REMEDIATION2;
+var init_check_mattpocock_skills = __esm({
+  "src/cli/lib/check-mattpocock-skills.ts"() {
+    REMEDIATION2 = "install via Claude Code plugin marketplace: `claude plugin install mattpocock-skills` (or git clone https://github.com/mattpocock/skills ~/.claude/skills/mattpocock-skills); methodology fallback already inline in role-prompts.yaml per v3.6.0 Phase 1 \u2014 install is optional but enables /grill-with-docs /zoom-out etc. SlashCommand acceleration";
+  }
+});
+
+// src/cli/lib/check-mcp-availability.ts
+var check_mcp_availability_exports = {};
+__export(check_mcp_availability_exports, {
+  checkMcpAvailability: () => checkMcpAvailability
+});
+async function checkMcpAvailability() {
+  const settingsPath3 = join(homedir(), ".claude", "settings.json");
+  let installed = [];
+  let missing = [...TARGET_SERVERS];
+  try {
+    const raw = await readFile(settingsPath3, "utf8");
+    const parsed = JSON.parse(raw);
+    const servers = parsed.mcpServers ?? {};
+    const serverNames = Object.keys(servers);
+    installed = TARGET_SERVERS.filter(
+      (s) => serverNames.some((n) => n.includes(s) || s.includes(n))
+    );
+    missing = TARGET_SERVERS.filter((s) => !installed.includes(s));
+  } catch {
+  }
+  if (missing.length === 0) {
+    return {
+      name: "MCP servers (tavily/exa/chrome-devtools)",
+      status: "pass",
+      message: `all 3 installed: ${installed.join(", ")}`
+    };
+  }
+  if (installed.length === 0) {
+    return {
+      name: "MCP servers (tavily/exa/chrome-devtools)",
+      status: "warn",
+      message: "none of 3 target MCP servers installed in ~/.claude/settings.json",
+      fix: "install via `claude mcp add <server-name>`; harnessed routes web-search to tavily/exa per workflows/judgments/web-search-routing.yaml \u2014 without them, falls back to WebFetch/WebSearch built-in (degraded but functional)"
+    };
+  }
+  return {
+    name: "MCP servers (tavily/exa/chrome-devtools)",
+    status: "warn",
+    message: `${installed.length}/3 installed: ${installed.join(", ")}; missing: ${missing.join(", ")}`,
+    fix: `install missing via \`claude mcp add ${missing.join(" && claude mcp add ")}\``
+  };
+}
+var TARGET_SERVERS;
+var init_check_mcp_availability = __esm({
+  "src/cli/lib/check-mcp-availability.ts"() {
+    TARGET_SERVERS = ["tavily-mcp", "exa-mcp", "chrome-devtools"];
+  }
+});
 function statePath() {
   return harnessedFile("current-workflow.json");
 }
@@ -853,7 +952,7 @@ var init_resume = __esm({
 
 // package.json
 var package_default = {
-  version: "3.5.0"};
+  version: "3.6.0"};
 
 // src/manifest/errors.ts
 function instancePathToKeyPath(instancePath) {
@@ -1704,7 +1803,7 @@ function renderHumanTable(records) {
   }
 }
 function pipeToJq(filterExpr, lines) {
-  return new Promise((resolve14, reject) => {
+  return new Promise((resolve15, reject) => {
     const child = spawn("jq", [filterExpr], {
       stdio: ["pipe", "inherit", "inherit"],
       windowsHide: true
@@ -1713,12 +1812,12 @@ function pipeToJq(filterExpr, lines) {
       const e = err2;
       if (e.code === "ENOENT") {
         console.error(t("audit_log.jq_missing"));
-        resolve14(1);
+        resolve15(1);
       } else {
         reject(err2);
       }
     });
-    child.on("close", (code) => resolve14(code ?? 0));
+    child.on("close", (code) => resolve15(code ?? 0));
     child.stdin.write(lines.join("\n"));
     child.stdin.end();
   });
@@ -2026,18 +2125,26 @@ async function checkAgentTeamsEnv() {
 async function checkPlanningPlugin() {
   return (await Promise.resolve().then(() => (init_check_planning_with_files(), check_planning_with_files_exports))).checkPlanningWithFiles();
 }
+async function checkMattpocockSkillsInstall() {
+  return (await Promise.resolve().then(() => (init_check_mattpocock_skills(), check_mattpocock_skills_exports))).checkMattpocockSkills();
+}
+async function checkMcpAvailabilityCheck() {
+  return (await Promise.resolve().then(() => (init_check_mcp_availability(), check_mcp_availability_exports))).checkMcpAvailability();
+}
 function registerDoctor(program2) {
   program2.command("doctor").description(
-    "Preflight checks (Node / MCP scope / jq / Win bash / origin URL / gstack prefix / deprecations / token budget / Agent Teams / planning-with-files)"
+    "Preflight checks (Node / MCP scope / jq / Win bash / origin URL / gstack prefix / deprecations / token budget / Agent Teams / planning-with-files / mattpocock-skills / MCP availability)"
   ).option("--json", "output JSON instead of human-readable").action(async (opts) => {
-    const [mcp, origin, gstack, dep, tok, at, ppwf] = await Promise.all([
+    const [mcp, origin, gstack, dep, tok, at, ppwf, matt, mcpAvail] = await Promise.all([
       checkMcpScope(),
       checkOriginUrl(),
       checkGstackPrefix(),
       checkDeprecations2(),
       checkTokenBudget2(),
       checkAgentTeamsEnv(),
-      checkPlanningPlugin()
+      checkPlanningPlugin(),
+      checkMattpocockSkillsInstall(),
+      checkMcpAvailabilityCheck()
     ]);
     const results = [
       checkNodeVersion(),
@@ -2049,7 +2156,9 @@ function registerDoctor(program2) {
       dep,
       tok,
       at,
-      ppwf
+      ppwf,
+      matt,
+      mcpAvail
     ];
     const hasFail = results.some((r) => r.status === "fail");
     const hasWarn = results.some((r) => r.status === "warn");
@@ -2530,6 +2639,22 @@ var JudgmentRulesFile = Type.Object(
   { additionalProperties: false }
 );
 Type.Union([JudgmentTriggersFile, JudgmentRulesFile]);
+var UserOverrideEntry = Type.Object(
+  {
+    id: Type.String({ minLength: 1 }),
+    // kebab-case (e.g. 'brainstorm', 'arch-review')
+    keywords: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
+    triggers: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 })
+  },
+  { additionalProperties: false }
+);
+var UserOverridesFile = Type.Object(
+  {
+    schema_version: Type.Literal("harnessed.user-overrides.v1"),
+    overrides: Type.Array(UserOverrideEntry, { minItems: 1 })
+  },
+  { additionalProperties: false }
+);
 
 // src/workflow/judgmentResolver.ts
 var TriggerNotFoundError = class extends Error {
@@ -2544,6 +2669,10 @@ var TriggerNotFoundError = class extends Error {
 };
 var _fileCache = /* @__PURE__ */ new Map();
 async function resolveJudgmentGate(gateRef, context, packageRoot) {
+  const userOverrides = context.user_overrides;
+  if (Array.isArray(userOverrides) && userOverrides.includes(gateRef)) {
+    return true;
+  }
   const parts = gateRef.split(".");
   if (parts.length !== 4 || parts[0] !== "judgments") {
     throw new Error(`Invalid gate ref: ${gateRef}`);
@@ -3193,13 +3322,33 @@ Five triggers (any one suffices):
 5. **fullstack_three_way** \u2014 the task is a synchronized fullstack push (frontend + backend + tests) requiring API contract alignment across three roles simultaneously.
 
 If none of the five apply, omit \`needs_teams_escalation\` (defaults to false) and proceed normally.`;
+var TRANSPARENT_SKIP_RULES = `When you encounter a phase gate or routing decision where the input context is missing key fields, default-valued, or contradictory, do NOT proceed silently. Instead, skip the phase and emit a one-line transparent explanation:
+
+  "Skipped <phase>, because <reason>. Tell me if you actually need it."
+  (\u4E2D\u6587: "\u8FD9\u6B21\u8DF3\u8FC7\u4E86 <phase>, \u56E0\u4E3A <reason>. \u5982\u679C\u4F60\u8BA4\u4E3A\u9700\u8981\u8BF7\u660E\u8BF4.")
+
+This applies to: strategic-layer review skip / phase-layer clarification skip / subtask-brainstorming skip / TDD enforcement skip / Agent Teams escalation skip. Chain-isolation rule: skipping one layer does NOT mandate skipping subsequent layers \u2014 each layer is independently evaluated.`;
+var AGENT_TEAMS_PREVENTION_RULES = `If you signal needs_teams_escalation=true, ALSO advise the user on these 4 Agent Teams prevention rules in your escalation_reason or summary (the user will be the one calling TeamCreate / SendMessage / TeamDelete; remind them upfront):
+
+1. **Session-scoped**: Teams live only in the current Claude Code session. \`/resume\` loses all teammates. Do not treat teams as persistent state \u2014 finish team work within one session.
+
+2. **Cleanup mandatory**: Before session ends, send \`SendMessage(to=<teammate>, content="shutdown_request")\` to each teammate, then call \`TeamDelete\`. Orphan teammates consume resources. This is a hard rule, not advisory.
+
+3. **Token cost estimation**: Before creating a team, estimate \`team_cost \u2248 N_teammates \xD7 N_rounds \xD7 avg_tokens_per_round + N_teammates \xD7 initial_brief_tokens\`. Compare to subagent fan-out cost (\`\u2248 N_subagents \xD7 (initial_brief + summary_tokens)\`). Only open a team when \`team_cost < 2 \xD7 subagent_cost\` \u2014 otherwise prefer fan-out.
+
+4. **Brief must be self-contained**: Each teammate launches WITHOUT main-session context. The Agent() prompt must include enough background, file paths, success criteria, and counter-positions so the teammate can work independently. Generic prompts produce shallow output.`;
+var CRITICAL_SYSTEM_REMINDER = `${ESCALATION_RULES}
+
+${TRANSPARENT_SKIP_RULES}
+
+${AGENT_TEAMS_PREVENTION_RULES}`;
 function buildAgentDef(skillName, rolePrompts, workflowName, modelTierOverride) {
   const rp = rolePrompts?.[skillName] ?? (workflowName ? rolePrompts?.[workflowName] : void 0);
   if (!rp) {
     return {
       description: `harnessed workflow phase: ${skillName}`,
       prompt: `You are executing the '${skillName}' workflow phase. Follow the phase intent and emit a structured COMPLETE signal when done.`,
-      criticalSystemReminder_EXPERIMENTAL: ESCALATION_RULES,
+      criticalSystemReminder_EXPERIMENTAL: CRITICAL_SYSTEM_REMINDER,
       ...modelTierOverride ? { model: modelTierOverride } : {}
     };
   }
@@ -3220,7 +3369,7 @@ ${rp.checklist.map((c, i) => `  ${i + 1}. ${c}`).join("\n")}` : "";
   return {
     description: rp.description,
     prompt,
-    criticalSystemReminder_EXPERIMENTAL: ESCALATION_RULES,
+    criticalSystemReminder_EXPERIMENTAL: CRITICAL_SYSTEM_REMINDER,
     ...modelTierOverride ? { model: modelTierOverride } : {}
   };
 }
@@ -3436,6 +3585,46 @@ function getPackageRoot() {
   }
   return resolve(thisDir, "..", "..", "..");
 }
+async function loadUserOverrides(packageRoot) {
+  const yamlPath = resolve(packageRoot, "workflows", "judgments", "user-overrides.yaml");
+  let raw;
+  try {
+    raw = await readFile(yamlPath, "utf8");
+  } catch {
+    return [];
+  }
+  let parsed;
+  try {
+    parsed = parse(raw);
+  } catch {
+    return [];
+  }
+  if (!Value.Check(UserOverridesFile, parsed)) {
+    return [];
+  }
+  const valid = parsed;
+  return valid.overrides.map((o) => ({
+    id: o.id,
+    keywords: [...o.keywords],
+    triggers: [...o.triggers]
+  }));
+}
+function extractMatchedTriggers(userText, overrides) {
+  if (!userText || overrides.length === 0) return [];
+  const haystack = userText.toLowerCase();
+  const matched = /* @__PURE__ */ new Set();
+  for (const entry of overrides) {
+    for (const kw of entry.keywords) {
+      if (haystack.includes(kw.toLowerCase())) {
+        for (const trigger of entry.triggers) matched.add(trigger);
+        break;
+      }
+    }
+  }
+  return [...matched];
+}
+
+// src/cli/run.ts
 var PACKAGE_ROOT = getPackageRoot();
 var WORKFLOWS_DIR = join(PACKAGE_ROOT, "workflows");
 var _autoChainCache = null;
@@ -3473,11 +3662,19 @@ function registerRun(program2) {
       );
       process.exit(2);
     }
+    const overrides = await loadUserOverrides(PACKAGE_ROOT);
+    const matchedTriggers = extractMatchedTriggers(task, overrides);
+    if (matchedTriggers.length > 0) {
+      console.error(
+        `\u2139 user-override detected: ${matchedTriggers.length} trigger(s) forced fires=true via keyword match (${matchedTriggers.join(", ")})`
+      );
+    }
     const gateContext = {
       task,
       ...raw.model ? { modelOverride: raw.model } : {},
       ...raw.maxIterations ? { maxIterations: raw.maxIterations } : {},
-      ...raw.staged ? { staged: true } : {}
+      ...raw.staged ? { staged: true } : {},
+      ...matchedTriggers.length > 0 ? { user_overrides: matchedTriggers } : {}
     };
     if (raw.dryRun) {
       console.log(JSON.stringify({ workflow: name, yamlPath, gateContext }, null, 2));
@@ -4052,7 +4249,7 @@ async function isPluginRegistered(pluginName) {
   return Object.keys(plugins).some((k) => k.split("@")[0] === pluginName);
 }
 function runArgs(claudeArgs, cwd, timeoutMs = 15e3) {
-  return new Promise((resolve14) => {
+  return new Promise((resolve15) => {
     const isWin = process.platform === "win32";
     const child = isWin ? spawn("cmd.exe", ["/c", "claude", ...claudeArgs], { cwd, windowsHide: true }) : spawn("claude", claudeArgs, { cwd, shell: false });
     let stderr = "";
@@ -4061,15 +4258,15 @@ function runArgs(claudeArgs, cwd, timeoutMs = 15e3) {
     });
     const timer = setTimeout(() => {
       child.kill("SIGKILL");
-      resolve14({ exitCode: -1, stderr: `${stderr}[timeout after ${timeoutMs}ms]` });
+      resolve15({ exitCode: -1, stderr: `${stderr}[timeout after ${timeoutMs}ms]` });
     }, timeoutMs);
     child.on("error", (e) => {
       clearTimeout(timer);
-      resolve14({ exitCode: -1, stderr: `${stderr}${e.message}` });
+      resolve15({ exitCode: -1, stderr: `${stderr}${e.message}` });
     });
     child.on("close", (code) => {
       clearTimeout(timer);
-      resolve14({ exitCode: code ?? -1, stderr });
+      resolve15({ exitCode: code ?? -1, stderr });
     });
   });
 }
@@ -4248,10 +4445,10 @@ async function spawnCmd(ctx, cmd, args, timeoutMs) {
   child.stderr?.setEncoding("utf8").on("data", (chunk) => {
     stderr += chunk;
   });
-  return await new Promise((resolve14) => {
+  return await new Promise((resolve15) => {
     const timer = setTimeout(() => {
       child.kill("SIGKILL");
-      resolve14({
+      resolve15({
         ok: false,
         phase: "spawn",
         error: {
@@ -4266,7 +4463,7 @@ async function spawnCmd(ctx, cmd, args, timeoutMs) {
     }, effectiveTimeoutMs);
     child.on("error", (err2) => {
       clearTimeout(timer);
-      resolve14({
+      resolve15({
         ok: false,
         phase: "spawn",
         error: {
@@ -4281,14 +4478,14 @@ async function spawnCmd(ctx, cmd, args, timeoutMs) {
     });
     child.on("close", (code) => {
       clearTimeout(timer);
-      resolve14({ ok: true, exitCode: code ?? -1, stdout: stdout2, stderr });
+      resolve15({ ok: true, exitCode: code ?? -1, stdout: stdout2, stderr });
     });
   });
 }
 
 // src/installers/gitCloneWithSetup.ts
 function gitRevParseHead(cwd, timeoutMs = 1e4) {
-  return new Promise((resolve14) => {
+  return new Promise((resolve15) => {
     const isWin = process.platform === "win32";
     const child = isWin ? spawn("cmd.exe", ["/c", "git", "rev-parse", "HEAD"], { cwd, windowsHide: true }) : spawn("git", ["rev-parse", "HEAD"], { cwd, shell: false });
     let stdout2 = "";
@@ -4297,15 +4494,15 @@ function gitRevParseHead(cwd, timeoutMs = 1e4) {
     });
     const timer = setTimeout(() => {
       child.kill("SIGKILL");
-      resolve14({ sha: "", exit: -1 });
+      resolve15({ sha: "", exit: -1 });
     }, timeoutMs);
     child.on("error", () => {
       clearTimeout(timer);
-      resolve14({ sha: "", exit: -1 });
+      resolve15({ sha: "", exit: -1 });
     });
     child.on("close", (code) => {
       clearTimeout(timer);
-      resolve14({ sha: stdout2.trim(), exit: code ?? -1 });
+      resolve15({ sha: stdout2.trim(), exit: code ?? -1 });
     });
   });
 }
@@ -6238,7 +6435,7 @@ var uninstallNpmCli = async (ctx) => {
   const m = install.cmd.match(/npm\s+(?:install|i)\s+(?:-g\s+)?(\S+)/);
   const pkg = m?.[1] ?? ctx.manifest.metadata.upstream.source;
   const isWin = process.platform === "win32";
-  const result = await new Promise((resolve14) => {
+  const result = await new Promise((resolve15) => {
     const child = isWin ? spawn("cmd.exe", ["/c", "npm", "uninstall", "-g", pkg], { windowsHide: true }) : spawn("npm", ["uninstall", "-g", pkg], { shell: false });
     let stderr = "";
     child.stderr?.setEncoding("utf8").on("data", (c) => {
@@ -6246,15 +6443,15 @@ var uninstallNpmCli = async (ctx) => {
     });
     const timer = setTimeout(() => {
       child.kill("SIGKILL");
-      resolve14({ exitCode: -1, stderr: `${stderr}[timeout]` });
+      resolve15({ exitCode: -1, stderr: `${stderr}[timeout]` });
     }, 3e4);
     child.on("error", (e) => {
       clearTimeout(timer);
-      resolve14({ exitCode: -1, stderr: e.message });
+      resolve15({ exitCode: -1, stderr: e.message });
     });
     child.on("close", (code) => {
       clearTimeout(timer);
-      resolve14({ exitCode: code ?? -1, stderr });
+      resolve15({ exitCode: code ?? -1, stderr });
     });
   });
   if (result.exitCode !== 0) {