harnessed 2.0.1 → 3.0.1

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { spawnSync, spawn } from 'child_process';
+import { execSync, spawnSync, spawn } from 'child_process';
 import { writeFileSync, existsSync, readFileSync, mkdirSync, appendFileSync, readdirSync } from 'fs';
 import { resolve, join, dirname, relative } from 'path';
 import { Type } from '@sinclair/typebox';
@@ -169,17 +169,21 @@ var init_schemaVersion = __esm({
       governance: "harnessed.governance.v1",
       // ← Phase 3.2 W1 T1.1 ADD 10th surface (D-04 PUSH veto status)
       planFeature: "harnessed.plan-feature.v1",
-      // ← Phase 3.3 W0 T0.5 BACKFILL 11th surface (sister Phase 3.2 W2 T2.2 b875e21 commit msg claim "11th surface" was LATENT STALE — never registered; T0.5 surgical fix per sister Phase 3.2 W2 T2.6 latent W1 c37ee29 Rule 1 pattern)
+      // ← Phase 3.3 W0 T0.5 BACKFILL 11th surface
       aliases: "harnessed.aliases.v1",
-      // ← Phase 3.3 W1 T1.1 ADD 12th surface (D-01 RICH manifests/aliases.yaml upstream rename redirect + metadata)
+      // ← Phase 3.3 W1 T1.1 ADD 12th surface (D-01 RICH)
       knownGood: "harnessed.known-good.v1",
-      // ← Phase 3.3 W1 T1.1 ADD 13th surface (D-03 YAML versions/<harnessed-ver>-known-good.yaml per-version lock)
+      // ← Phase 3.3 W1 T1.1 ADD 13th surface (D-03 YAML manifest)
       capabilities: "harnessed.capabilities.v1",
-      // ← Phase v2.0-2.3 W0 T2.3.W0.6 ADD 14th surface (R20.2 flat yaml capabilities manifest validate)
+      // ← Phase v2.0-2.3 W0 ADD 14th surface (R20.2 flat yaml capabilities manifest validate)
       judgment: "harnessed.judgment.v1",
-      // ← Phase v2.0-2.3 W0 T2.3.W0.6 ADD 15th surface (R20.4 multi-file judgments triggers/rules validate)
-      workflow: "harnessed.workflow.v2"
-      // ← Phase v2.0-2.4 W0 T2.4.W0.1 ADD 16th surface (R20.1 + R20.2 + R20.9 — workflow.yaml v2 schema: gate / on / capability / args / fallback / parallelism 字段, sister 4 workflow.yaml: plan-feature + execute-task + research + verify-work)
+      // ← Phase v2.0-2.3 W0 ADD 15th surface (R20.4 multi-file judgments validate)
+      workflow: "harnessed.workflow.v2",
+      // ← Phase v2.0-2.4 W0 T2.4.W0.1 ADD 16th surface (R20.1+R20.2+R20.9 workflow.yaml v2)
+      workflow_v3: "harnessed.workflow.v3",
+      // ← Phase v3.0-3.3 W0 T3.3.W0.11 ADD 17th surface (D-09 disciplines_applied + D-05 tools_available + master delegates_to per Pattern A B.1 LOCK)
+      discipline: "harnessed.discipline.v1"
+      // ← Phase v3.0-3.3 W0 T3.3.W0.11 ADD 18th surface (D-09 L0 Discipline Substrate, sister judgment.v1 multi-file pattern)
     };
     Type.Union([
       Type.Literal(SCHEMA_VERSIONS.routingSnapshot),
@@ -202,11 +206,15 @@ var init_schemaVersion = __esm({
       Type.Literal(SCHEMA_VERSIONS.knownGood),
       // ← Phase 3.3 W1 T1.1 ADD 13th surface
       Type.Literal(SCHEMA_VERSIONS.capabilities),
-      // ← Phase v2.0-2.3 W0 T2.3.W0.6 ADD 14th surface
+      // ← Phase v2.0-2.3 W0 ADD 14th surface
       Type.Literal(SCHEMA_VERSIONS.judgment),
-      // ← Phase v2.0-2.3 W0 T2.3.W0.6 ADD 15th surface
-      Type.Literal(SCHEMA_VERSIONS.workflow)
-      // ← Phase v2.0-2.4 W0 T2.4.W0.1 ADD 16th surface (workflow.yaml v2 schema, NOTE first .v2 surface in union)
+      // ← Phase v2.0-2.3 W0 ADD 15th surface
+      Type.Literal(SCHEMA_VERSIONS.workflow),
+      // ← Phase v2.0-2.4 W0 T2.4.W0.1 ADD 16th surface (first .v2 in union)
+      Type.Literal(SCHEMA_VERSIONS.workflow_v3),
+      // ← Phase v3.0-3.3 W0 T3.3.W0.11 ADD 17th surface (first .v3 in union)
+      Type.Literal(SCHEMA_VERSIONS.discipline)
+      // ← Phase v3.0-3.3 W0 T3.3.W0.11 ADD 18th surface
     ]);
   }
 });
@@ -692,10 +700,10 @@ __export(knownGood_exports, {
   loadKnownGood: () => loadKnownGood
 });
 function loadKnownGood(harnessedVer) {
-  if (_cache.has(harnessedVer)) return _cache.get(harnessedVer) ?? null;
+  if (_cache2.has(harnessedVer)) return _cache2.get(harnessedVer) ?? null;
   const path = join(versionsDir(), `${harnessedVer}-known-good.yaml`);
   if (!existsSync(path)) {
-    _cache.set(harnessedVer, null);
+    _cache2.set(harnessedVer, null);
     return null;
   }
   const raw = readFileSync(path, "utf8");
@@ -706,7 +714,7 @@ function loadKnownGood(harnessedVer) {
       `${path} schema invalid: ${errs.map((e) => `${e.path} ${e.message}`).join("; ")}`
     );
   }
-  _cache.set(harnessedVer, parsed);
+  _cache2.set(harnessedVer, parsed);
   return parsed;
 }
 function getPinnedVersion(upstreamName, harnessedVer) {
@@ -715,12 +723,12 @@ function getPinnedVersion(upstreamName, harnessedVer) {
   const entry = kg.upstreams.find((u) => u.name === upstreamName);
   return entry?.version ?? null;
 }
-var versionsDir, _cache;
+var versionsDir, _cache2;
 var init_knownGood = __esm({
   "src/manifest/knownGood.ts"() {
     init_known_good_v1();
     versionsDir = () => join(process.cwd(), "versions");
-    _cache = /* @__PURE__ */ new Map();
+    _cache2 = /* @__PURE__ */ new Map();
   }
 });
 
@@ -785,7 +793,7 @@ var init_resume = __esm({
 
 // package.json
 var package_default = {
-  version: "2.0.1"};
+  version: "3.0.1"};
 
 // src/manifest/errors.ts
 function instancePathToKeyPath(instancePath) {
@@ -1566,7 +1574,7 @@ function renderHumanTable(records) {
   }
 }
 function pipeToJq(filterExpr, lines) {
-  return new Promise((resolve8, reject) => {
+  return new Promise((resolve9, reject) => {
     const child = spawn("jq", [filterExpr], {
       stdio: ["pipe", "inherit", "inherit"],
       windowsHide: true
@@ -1575,12 +1583,12 @@ function pipeToJq(filterExpr, lines) {
       const e = err2;
       if (e.code === "ENOENT") {
         console.error("\u2717 jq not found in PATH \u2014 run: harnessed doctor");
-        resolve8(1);
+        resolve9(1);
       } else {
         reject(err2);
       }
     });
-    child.on("close", (code) => resolve8(code ?? 0));
+    child.on("close", (code) => resolve9(code ?? 0));
     child.stdin.write(lines.join("\n"));
     child.stdin.end();
   });
@@ -1932,6 +1940,107 @@ function registerDoctor(program2) {
   });
 }
 
+// src/workflow/schema/discipline.ts
+init_schemaVersion();
+var EnforcementLayer = Type.Union([
+  Type.Literal("code-writing"),
+  // karpathy 心法 — write code phase
+  Type.Literal("output"),
+  // BLUF / language / no-emoji — emit response phase
+  Type.Literal("commit"),
+  // biome / A7 / commit safety — pre-commit phase
+  Type.Literal("workflow"),
+  // priority hierarchy / protocols — workflow-level arbitration
+  Type.Literal("tool")
+  // tool invoke discipline (reserved for v3.x extension)
+]);
+var Enforcement = Type.Union([
+  Type.Literal("halt"),
+  // process.exit non-zero, sister fallbackHandlers
+  Type.Literal("warn"),
+  // console.warn emit, continue
+  Type.Literal("auto-fix"),
+  // run auto_fix_cmd then continue (biome --write pattern)
+  Type.Literal("info")
+  // log only, no action
+]);
+var DisciplineRule = Type.Object(
+  {
+    id: Type.String({ minLength: 1 }),
+    // kebab-case
+    description: Type.String(),
+    // human-readable
+    enforcement: Enforcement,
+    trigger: Type.Union([Type.String(), Type.Array(Type.String())]),
+    // expr OR always-on list
+    check_method: Type.String(),
+    // heuristic / regex / external-cmd / llm-judge / file-content-match
+    auto_fix_cmd: Type.Optional(Type.String())
+    // only enforcement=auto-fix
+  },
+  { additionalProperties: false }
+);
+var PriorityHierarchy = Type.Array(Type.String(), { minItems: 1 });
+var ProtocolShape = Type.Object(
+  {
+    description: Type.String(),
+    required_fields: Type.Optional(Type.Array(Type.String())),
+    forbidden_phrases: Type.Optional(Type.Array(Type.String())),
+    file_ownership: Type.Optional(Type.Record(Type.String(), Type.Array(Type.String()))),
+    rules: Type.Optional(Type.Array(DisciplineRule))
+  },
+  { additionalProperties: false }
+);
+var Discipline = Type.Object(
+  {
+    schema_version: Type.Literal(SCHEMA_VERSIONS.discipline),
+    discipline: Type.String({ minLength: 1 }),
+    // basename (karpathy / output-style / ...)
+    enforcement_layer: EnforcementLayer,
+    auto_enforce: Type.Boolean(),
+    rules: Type.Array(DisciplineRule),
+    priority_hierarchy: Type.Optional(PriorityHierarchy),
+    // priority.yaml only
+    protocols: Type.Optional(Type.Record(Type.String(), ProtocolShape))
+    // protocols.yaml only
+  },
+  { additionalProperties: false }
+);
+
+// src/workflow/disciplineLoader.ts
+var _cache = /* @__PURE__ */ new Map();
+async function loadDiscipline(basename2, packageRoot) {
+  const cached = _cache.get(basename2);
+  if (cached) return cached;
+  const yamlPath = resolve(packageRoot, "workflows", "disciplines", `${basename2}.yaml`);
+  const raw = await readFile(yamlPath, "utf8");
+  const parsedRaw = parse(raw);
+  if (!Value.Check(Discipline, parsedRaw)) {
+    const errors = [...Value.Errors(Discipline, parsedRaw)].slice(0, 3).map((e) => `${e.path} ${e.message}`).join("; ");
+    throw new Error(`Invalid discipline file ${basename2}.yaml: ${errors}`);
+  }
+  const parsed = parsedRaw;
+  _cache.set(basename2, parsed);
+  return parsed;
+}
+
+// src/discipline/enforcement/before-commit.ts
+var TS_JS_RE = /\.(ts|tsx|js|mjs)$/;
+async function runBeforeCommitHook(ctx) {
+  const d = await loadDiscipline("operational", ctx.packageRoot);
+  if (ctx.changedFiles.some((f) => TS_JS_RE.test(f))) {
+    const rule = d.rules.find((r) => r.id === "biome-preempt");
+    if (rule?.auto_fix_cmd) {
+      console.warn("\u26A0\uFE0F biome preempt \u2014 running auto-fix before commit");
+      execSync(rule.auto_fix_cmd, { cwd: ctx.packageRoot, stdio: "inherit" });
+    }
+  }
+  if (ctx.cmdArgs.includes("--no-verify")) {
+    console.error("\u274C no-skip-hooks violated: --no-verify forbidden");
+    process.exit(2);
+  }
+}
+
 // src/routing/completionSchema.ts
 var COMPLETION_SCHEMA = {
   type: "object",
@@ -2636,15 +2745,100 @@ var PhasesSchema = Type.Object(
 
 // src/workflow/schema/workflow.ts
 init_schemaVersion();
+
+// src/workflow/schema/workflow.v2.ts
+init_schemaVersion();
 var ModelTier2 = Type.Union([Type.Literal("haiku"), Type.Literal("sonnet"), Type.Literal("opus")]);
 var OnAction = Type.Union([Type.Literal("skip"), Type.Literal("invoke")]);
+var OnClauseV2 = Type.Object(
+  {
+    if: Type.String(),
+    invoke: Type.Optional(Type.String()),
+    action: Type.Optional(OnAction)
+  },
+  { additionalProperties: false }
+);
+var FallbackMaxIterationsExceededV2 = Type.Object(
+  {
+    action: Type.Literal("emit_warning_and_halt"),
+    message: Type.String(),
+    exit_code: Type.Number()
+  },
+  { additionalProperties: false }
+);
+var PhaseFallbackV2 = Type.Object(
+  {
+    max_iterations_exceeded: Type.Optional(FallbackMaxIterationsExceededV2)
+  },
+  { additionalProperties: false }
+);
+var WorkflowPhaseV2 = Type.Object(
+  {
+    id: Type.String({ minLength: 1 }),
+    name: Type.Optional(Type.String()),
+    upstream: Type.Optional(Type.String()),
+    capability: Type.Optional(Type.String()),
+    model: Type.Optional(ModelTier2),
+    invokes: Type.Optional(Type.String()),
+    args: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+    gate: Type.Optional(Type.String()),
+    on: Type.Optional(Type.Array(OnClauseV2)),
+    parallelism: Type.Optional(Type.String()),
+    fallback: Type.Optional(PhaseFallbackV2),
+    max_iterations: Type.Optional(Type.Union([Type.Number(), Type.String()])),
+    artifacts_expected: Type.Optional(Type.Array(Type.String()))
+  },
+  { additionalProperties: false }
+);
+var WorkflowSchemaV2 = Type.Object(
+  {
+    schema_version: Type.Literal(SCHEMA_VERSIONS.workflow),
+    workflow: Type.String({ minLength: 1 }),
+    description: Type.Optional(Type.String()),
+    phases: Type.Array(WorkflowPhaseV2, { minItems: 1 })
+  },
+  { additionalProperties: false }
+);
+
+// src/workflow/schema/workflow.ts
+var ModelTier3 = Type.Union([Type.Literal("haiku"), Type.Literal("sonnet"), Type.Literal("opus")]);
+var OnAction2 = Type.Union([Type.Literal("skip"), Type.Literal("invoke")]);
+var DisciplineName = Type.Union([
+  Type.Literal("karpathy"),
+  Type.Literal("output-style"),
+  Type.Literal("language"),
+  Type.Literal("operational"),
+  Type.Literal("priority"),
+  Type.Literal("protocols")
+]);
 var OnClause = Type.Object(
   {
     if: Type.String(),
     // expr-eval expression OR judgments.<file>.<gate>.fires ref
     invoke: Type.Optional(Type.String()),
     // '{{ capabilities.<name>.cmd }}' OR literal
-    action: Type.Optional(OnAction)
+    action: Type.Optional(OnAction2)
+  },
+  { additionalProperties: false }
+);
+var InvokeToolClause = Type.Object(
+  {
+    if: Type.Optional(Type.String()),
+    // optional — 无 if = unconditional fire
+    tool: Type.String({ minLength: 1 })
+    // capabilities.yaml entry name (cross-validate T3.3.W0.10)
+  },
+  { additionalProperties: false }
+);
+var DelegationClause = Type.Object(
+  {
+    sub: Type.String({ minLength: 1 }),
+    // sub-stage workflow name e.g. 'strategic' / 'phase' / 'subtask'
+    gate: Type.Optional(Type.String()),
+    // judgments.<file>.<trigger>.fires 4-level ref
+    mode: Type.Optional(Type.Union([Type.Literal("parallel"), Type.Literal("serial")])),
+    order: Type.Optional(Type.Number())
+    // serial-only: explicit ordering (K9 mitigation enforced in check-workflow-schema)
   },
   { additionalProperties: false }
 );
@@ -2663,14 +2857,14 @@ var PhaseFallback = Type.Object(
   },
   { additionalProperties: false }
 );
-var WorkflowPhaseV2 = Type.Object(
+var WorkflowPhaseV3 = Type.Object(
   {
     id: Type.String({ minLength: 1 }),
     name: Type.Optional(Type.String()),
     upstream: Type.Optional(Type.String()),
     capability: Type.Optional(Type.String()),
     // '{{ capabilities.ralph-loop.cmd }}'
-    model: Type.Optional(ModelTier2),
+    model: Type.Optional(ModelTier3),
     invokes: Type.Optional(Type.String()),
     // legacy slash-cmd OR JINJA template
     args: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
@@ -2684,16 +2878,25 @@ var WorkflowPhaseV2 = Type.Object(
       Type.Union([Type.Number(), Type.String()])
       // numeric literal OR jinja '{{ defaults.x.y }}'
     ),
-    artifacts_expected: Type.Optional(Type.Array(Type.String()))
+    artifacts_expected: Type.Optional(Type.Array(Type.String())),
+    invokes_tools: Type.Optional(Type.Array(InvokeToolClause))
+    // NEW v3 D-05 phase-level conditional fire
   },
   { additionalProperties: false }
 );
-var WorkflowSchemaV2 = Type.Object(
+Type.Object(
   {
-    schema_version: Type.Literal(SCHEMA_VERSIONS.workflow),
+    schema_version: Type.Literal(SCHEMA_VERSIONS.workflow_v3),
     workflow: Type.String({ minLength: 1 }),
     description: Type.Optional(Type.String()),
-    phases: Type.Array(WorkflowPhaseV2, { minItems: 1 })
+    disciplines_applied: Type.Optional(Type.Array(DisciplineName)),
+    // NEW v3 D-09 (Pattern A A.1 strict Literal Union)
+    tools_available: Type.Optional(Type.Array(Type.String())),
+    // NEW v3 D-05 (cross-validate T3.3.W0.10)
+    delegates_to: Type.Optional(Type.Array(DelegationClause)),
+    // NEW v3 D-01 (master orchestrator only)
+    phases: Type.Optional(Type.Array(WorkflowPhaseV3, { minItems: 1 }))
+    // 改 Optional — master 无 phases, sub/standalone 必有
   },
   { additionalProperties: false }
 );
@@ -2737,7 +2940,12 @@ function validateNonInteractiveFlags(raw, cmdName) {
 
 // src/cli/execute-task.ts
 function registerExecuteTask(program2) {
-  program2.command("execute-task").description("Run execute-task workflow (4-phase chain \u2192 ralph-loop COMPLETE)").requiredOption("--task <text>", "task description (required)").option("--workflow <name>", "workflow name", "execute-task").option("--apply", "execute the spawn (default: dry-run preview)").option("--dry-run", "force dry-run (overrides --apply if both set)").option("--non-interactive", "CI / scripts \u2014 requires --apply or --dry-run").option("--model <model>", "subagent model: 'haiku' | 'sonnet' | 'opus'").option("--model-tier <tier>", "override: 'inherit' bypasses per-phase phase.model (B-10)").option("--max-iterations <n>", "ralph-loop max iter (default 20)", (v) => parseInt(v, 10)).action(async (raw) => {
+  program2.command("execute-task").description(
+    "Run execute-task workflow (4-phase chain \u2192 ralph-loop COMPLETE; immediate by default \u2014 use --dry-run for preview)"
+  ).requiredOption("--task <text>", "task description (required)").option("--workflow <name>", "workflow name", "execute-task").option(
+    "--apply",
+    "(deprecated; kept for backward compat \u2014 execute-task spawns immediately by default)"
+  ).option("--dry-run", "preview only \u2014 do not spawn subagent (opt-in for advanced users)").option("--non-interactive", "CI / scripts \u2014 requires --apply or --dry-run").option("--model <model>", "subagent model: 'haiku' | 'sonnet' | 'opus'").option("--model-tier <tier>", "override: 'inherit' bypasses per-phase phase.model (B-10)").option("--max-iterations <n>", "ralph-loop max iter (default 20)", (v) => parseInt(v, 10)).action(async (raw) => {
     validateNonInteractiveFlags(raw, "execute-task --task <text>");
     if (!raw.task) {
       console.error("error: --task <text> is required");
@@ -2760,7 +2968,7 @@ function registerExecuteTask(program2) {
       };
     }
     const taskCtx = { task: raw.task, task_type: "execute-task" };
-    const isDryRun = raw.dryRun === true || !raw.apply && !raw.nonInteractive;
+    const isDryRun = raw.dryRun === true;
     if (isDryRun) {
       console.log(
         JSON.stringify({ workflow: phases.workflow, phases: phases.phases, taskCtx }, null, 2)
@@ -2776,6 +2984,22 @@ function registerExecuteTask(program2) {
         break;
       }
     }
+    try {
+      const stagedOut = execSync("git status --porcelain", { encoding: "utf8" });
+      const changedFiles = stagedOut.split("\n").filter((l) => l.trim().length > 0).map((l) => l.slice(3).trim());
+      await runBeforeCommitHook({
+        changedFiles,
+        cmdArgs: [],
+        packageRoot: process.cwd(),
+        cmdType: "git-commit",
+        hasUserApproval: true
+        // --apply explicit
+      });
+    } catch (err2) {
+      console.warn(
+        `\u26A0\uFE0F before-commit pre-flight skipped (${err2.message}); subagent will biome-check at commit time.`
+      );
+    }
     const result = await runRouting(taskCtx, {
       maxIterations: raw.maxIterations ?? 20,
       ...raw.model ? { agentOpts: { modelOverride: raw.model } } : {},
@@ -2822,8 +3046,10 @@ async function dirSizeKb(dir) {
   return Math.round(total / 1024);
 }
 function registerGc(program2) {
-  program2.command("gc").description("Garbage-collect old backup snapshots (dry-run by default)").option("--older-than <duration>", "delete snapshots older than (e.g. 30d / 24h / 4w)", "30d").option("--keep-last <N>", "always keep the most recent N snapshots", "0").option("--apply", "actually delete (default: dry-run preview only)").option("--dry-run", "force dry-run (overrides --apply)").action(async (opts) => {
-    const dryRun = opts.dryRun === true || opts.apply !== true;
+  program2.command("gc").description(
+    "Garbage-collect old backup snapshots (immediate by default \u2014 use --dry-run for preview)"
+  ).option("--older-than <duration>", "delete snapshots older than (e.g. 30d / 24h / 4w)", "30d").option("--keep-last <N>", "always keep the most recent N snapshots", "0").option("--apply", "(deprecated; kept for backward compat \u2014 gc deletes immediately by default)").option("--dry-run", "preview only \u2014 do not delete (opt-in for advanced users)").action(async (opts) => {
+    const dryRun = opts.dryRun === true;
     const olderMs = parseDuration(opts.olderThan ?? "30d");
     if (olderMs == null) {
       console.error(
@@ -2873,7 +3099,7 @@ function registerGc(program2) {
       console.log(`  ${c.ts}  ${c.manifest}  (${c.sizeKb} KB)`);
       if (!dryRun) await rm(c.path, { recursive: true, force: true });
     }
-    if (dryRun) console.log("\n(dry-run \u2014 re-run with --apply to actually delete)");
+    if (dryRun) console.log("\n(dry-run \u2014 re-run without --dry-run to actually delete)");
   });
 }
 async function confirmAt(level, ctx) {
@@ -3157,7 +3383,7 @@ var installCcHookAdd = async (ctx) => {
   return { ok: true, backupId: bk.backupId, appliedFiles: [settingsPath] };
 };
 function runArgs(claudeArgs, cwd, timeoutMs = 15e3) {
-  return new Promise((resolve8) => {
+  return new Promise((resolve9) => {
     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 = "";
@@ -3166,15 +3392,15 @@ function runArgs(claudeArgs, cwd, timeoutMs = 15e3) {
     });
     const timer = setTimeout(() => {
       child.kill("SIGKILL");
-      resolve8({ exitCode: -1, stderr: `${stderr}[timeout after ${timeoutMs}ms]` });
+      resolve9({ exitCode: -1, stderr: `${stderr}[timeout after ${timeoutMs}ms]` });
     }, timeoutMs);
     child.on("error", (e) => {
       clearTimeout(timer);
-      resolve8({ exitCode: -1, stderr: `${stderr}${e.message}` });
+      resolve9({ exitCode: -1, stderr: `${stderr}${e.message}` });
     });
     child.on("close", (code) => {
       clearTimeout(timer);
-      resolve8({ exitCode: code ?? -1, stderr });
+      resolve9({ exitCode: code ?? -1, stderr });
     });
   });
 }
@@ -3315,7 +3541,7 @@ ${newEntry}
       )
     };
   }
-  const vr = await new Promise((resolve8) => {
+  const vr = await new Promise((resolve9) => {
     const child = spawn(verifyShell, [verifyFlag, verifyLine], { cwd: ctx.cwd, windowsHide: true });
     let stderr = "";
     child.stderr?.setEncoding("utf8").on("data", (c) => {
@@ -3323,15 +3549,15 @@ ${newEntry}
     });
     const timer = setTimeout(() => {
       child.kill("SIGKILL");
-      resolve8({ exitCode: -1, stderr: `${stderr}[timeout]` });
+      resolve9({ exitCode: -1, stderr: `${stderr}[timeout]` });
     }, 15e3);
     child.on("error", (e) => {
       clearTimeout(timer);
-      resolve8({ exitCode: -1, stderr: e.message });
+      resolve9({ exitCode: -1, stderr: e.message });
     });
     child.on("close", (code) => {
       clearTimeout(timer);
-      resolve8({ exitCode: code ?? -1, stderr });
+      resolve9({ exitCode: code ?? -1, stderr });
     });
   });
   if (vr.exitCode !== 0) {
@@ -3387,10 +3613,10 @@ async function spawnCmd(ctx, cmd, args) {
   child.stderr?.setEncoding("utf8").on("data", (chunk) => {
     stderr += chunk;
   });
-  return await new Promise((resolve8) => {
+  return await new Promise((resolve9) => {
     const timer = setTimeout(() => {
       child.kill("SIGKILL");
-      resolve8({
+      resolve9({
         ok: false,
         phase: "spawn",
         error: {
@@ -3405,7 +3631,7 @@ async function spawnCmd(ctx, cmd, args) {
     }, timeoutMs);
     child.on("error", (err2) => {
       clearTimeout(timer);
-      resolve8({
+      resolve9({
         ok: false,
         phase: "spawn",
         error: {
@@ -3420,14 +3646,14 @@ async function spawnCmd(ctx, cmd, args) {
     });
     child.on("close", (code) => {
       clearTimeout(timer);
-      resolve8({ ok: true, exitCode: code ?? -1, stdout: stdout2, stderr });
+      resolve9({ ok: true, exitCode: code ?? -1, stdout: stdout2, stderr });
     });
   });
 }
 
 // src/installers/gitCloneWithSetup.ts
 function gitRevParseHead(cwd, timeoutMs = 1e4) {
-  return new Promise((resolve8) => {
+  return new Promise((resolve9) => {
     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 = "";
@@ -3436,15 +3662,15 @@ function gitRevParseHead(cwd, timeoutMs = 1e4) {
     });
     const timer = setTimeout(() => {
       child.kill("SIGKILL");
-      resolve8({ sha: "", exit: -1 });
+      resolve9({ sha: "", exit: -1 });
     }, timeoutMs);
     child.on("error", () => {
       clearTimeout(timer);
-      resolve8({ sha: "", exit: -1 });
+      resolve9({ sha: "", exit: -1 });
     });
     child.on("close", (code) => {
       clearTimeout(timer);
-      resolve8({ sha: stdout2.trim(), exit: code ?? -1 });
+      resolve9({ sha: stdout2.trim(), exit: code ?? -1 });
     });
   });
 }
@@ -3784,7 +4010,7 @@ ${newEntry}
       )
     };
   }
-  const vr = await new Promise((resolve8) => {
+  const vr = await new Promise((resolve9) => {
     const child = spawn(verifyShell, [verifyFlag, verifyLine], { cwd: ctx.cwd, windowsHide: true });
     let stderr = "";
     child.stderr?.setEncoding("utf8").on("data", (c) => {
@@ -3792,15 +4018,15 @@ ${newEntry}
     });
     const timer = setTimeout(() => {
       child.kill("SIGKILL");
-      resolve8({ exitCode: -1, stderr: `${stderr}[timeout]` });
+      resolve9({ exitCode: -1, stderr: `${stderr}[timeout]` });
     }, 15e3);
     child.on("error", (e) => {
       clearTimeout(timer);
-      resolve8({ exitCode: -1, stderr: e.message });
+      resolve9({ exitCode: -1, stderr: e.message });
     });
     child.on("close", (code) => {
       clearTimeout(timer);
-      resolve8({ exitCode: code ?? -1, stderr });
+      resolve9({ exitCode: code ?? -1, stderr });
     });
   });
   if (vr.exitCode !== 0) {
@@ -3932,7 +4158,7 @@ ${newEntry}
       )
     };
   }
-  const vr = await new Promise((resolve8) => {
+  const vr = await new Promise((resolve9) => {
     const child = spawn(verifyShell, [verifyFlag, verifyLine], { cwd: ctx.cwd, windowsHide: true });
     let stderr = "";
     child.stderr?.setEncoding("utf8").on("data", (c) => {
@@ -3940,15 +4166,15 @@ ${newEntry}
     });
     const timer = setTimeout(() => {
       child.kill("SIGKILL");
-      resolve8({ exitCode: -1, stderr: `${stderr}[timeout]` });
+      resolve9({ exitCode: -1, stderr: `${stderr}[timeout]` });
     }, 15e3);
     child.on("error", (e) => {
       clearTimeout(timer);
-      resolve8({ exitCode: -1, stderr: e.message });
+      resolve9({ exitCode: -1, stderr: e.message });
     });
     child.on("close", (code) => {
       clearTimeout(timer);
-      resolve8({ exitCode: code ?? -1, stderr });
+      resolve9({ exitCode: code ?? -1, stderr });
     });
   });
   if (vr.exitCode !== 0) {
@@ -4246,7 +4472,7 @@ function formatError(e) {
   return `${head}${where}${tip}`;
 }
 function registerInstall(program2) {
-  program2.command("install <name>").description("Install an upstream (dry-run by default \u2014 pass --apply to execute)").option("--apply", "execute the install (default: dry-run preview only)").option("--dry-run", "force dry-run (overrides --apply if both are set)").option("--system", "allow L4 system-wide install (e.g. global npm install)").option("--non-interactive", "skip all prompts (CI / scripts) \u2014 requires --apply or --dry-run").option("--full-diff", "expand diffs longer than 200 lines").option("--no-color", "disable ANSI colors (auto-detected when piped)").option(
+  program2.command("install <name>").description("Install an upstream (immediate by default \u2014 use --dry-run for preview)").option("--apply", "(deprecated; kept for backward compat \u2014 install is immediate by default)").option("--dry-run", "preview only \u2014 do not write to disk (opt-in for advanced users)").option("--system", "allow L4 system-wide install (e.g. global npm install)").option("--non-interactive", "skip all prompts (CI / scripts) \u2014 requires --apply or --dry-run").option("--full-diff", "expand diffs longer than 200 lines").option("--no-color", "disable ANSI colors (auto-detected when piped)").option(
     "--known-good",
     "use known-good version lock from versions/<harnessed-ver>-known-good.yaml"
   ).action(async (name, raw) => {
@@ -4278,9 +4504,10 @@ function registerInstall(program2) {
       console.error(`  fix:  run 'harnessed audit' to inspect manifest issues`);
       process.exit(1);
     }
+    const dryRun = raw.dryRun === true;
     const opts = {
-      apply: raw.apply === true,
-      dryRun: raw.dryRun === true,
+      apply: !dryRun,
+      dryRun,
       system: raw.system === true,
       nonInteractive: raw.nonInteractive === true,
       fullDiff: raw.fullDiff === true,
@@ -4326,11 +4553,17 @@ async function listBaseManifests(cwd) {
   return out;
 }
 function registerInstallBase(program2) {
-  program2.command("install-base").description("Install the phase 1.3 base profile (auto-glob manifests; dry-run by default)").option("--apply", "execute the install (default: dry-run preview only)").option("--dry-run", "force dry-run (overrides --apply if both are set)").option("--non-interactive", "skip all prompts (CI / scripts) \u2014 requires --apply or --dry-run").action(async (raw) => {
+  program2.command("install-base").description(
+    "Install the phase 1.3 base profile (immediate by default \u2014 use --dry-run for preview)"
+  ).option(
+    "--apply",
+    "(deprecated; kept for backward compat \u2014 install-base is immediate by default)"
+  ).option("--dry-run", "preview only \u2014 do not write to disk (opt-in for advanced users)").option("--non-interactive", "skip all prompts (CI / scripts) \u2014 requires --apply or --dry-run").action(async (raw) => {
     validateNonInteractiveFlags(raw, "install-base");
+    const dryRun = raw.dryRun === true;
     const opts = {
-      apply: raw.apply === true,
-      dryRun: raw.dryRun === true,
+      apply: !dryRun,
+      dryRun,
       system: false,
       nonInteractive: raw.nonInteractive === true,
       fullDiff: false,
@@ -4390,7 +4623,12 @@ function basename(upstream) {
   return (upstream.split("/").pop() ?? upstream).replace(/\.git$/, "");
 }
 function registerManifestAdd(program2) {
-  program2.command("manifest-add <upstream>").description("Add a new upstream adapter (EE-5 5-question merge gate, D-03 BOTH dry-run/apply)").option("--category <cat>", "manifest category (skill-packs | tools)", "skill-packs").option("--name <name>", "short adapter name (defaults to <upstream> basename)").option("--apply", "persist EE-5 answers (default: dry-run preview)").option("--dry-run", "force dry-run (overrides --apply if both set)").option("--non-interactive", "CI/scripts \u2014 requires --apply or --dry-run; WARN-only dry-run").action(async (upstream, raw) => {
+  program2.command("manifest-add <upstream>").description(
+    "Add a new upstream adapter (EE-5 5-question merge gate; immediate by default \u2014 use --dry-run for preview)"
+  ).option("--category <cat>", "manifest category (skill-packs | tools)", "skill-packs").option("--name <name>", "short adapter name (defaults to <upstream> basename)").option(
+    "--apply",
+    "(deprecated; kept for backward compat \u2014 manifest-add persists immediately by default)"
+  ).option("--dry-run", "preview only \u2014 do not write JSON (opt-in for advanced users)").option("--non-interactive", "CI/scripts \u2014 requires --apply or --dry-run; WARN-only dry-run").action(async (upstream, raw) => {
     validateNonInteractiveFlags(raw, "manifest-add <upstream>");
     const name = raw.name ?? basename(upstream);
     const category = raw.category ?? "skill-packs";
@@ -4419,7 +4657,8 @@ function registerManifestAdd(program2) {
       payload[f] = a;
     }
     rl.close();
-    if (raw.apply) {
+    const dryRun = raw.dryRun === true;
+    if (!dryRun) {
       writeFileSync(outPath, `${JSON.stringify(payload, null, 2)}
 `, "utf8");
       console.log(`[manifest-add] EE-5 gate passed; wrote ${outPath}`);
@@ -4433,14 +4672,19 @@ function registerManifestAdd(program2) {
 
 // src/cli/research.ts
 function registerResearch(program2) {
-  program2.command("research").description("Run research workflow (search category sub-routing \u2192 spawn \u2192 verbatim COMPLETE)").requiredOption("--query <text>", "research prompt (required)").option("--apply", "execute the spawn (default: dry-run preview only)").option("--dry-run", "force dry-run (overrides --apply if both are set)").option("--non-interactive", "skip all prompts (CI / scripts) \u2014 requires --apply or --dry-run").option("--model <model>", "subagent model: 'haiku' | 'sonnet' | 'opus'").action(async (raw) => {
+  program2.command("research").description(
+    "Run research workflow (search category sub-routing \u2192 spawn \u2192 verbatim COMPLETE; immediate by default \u2014 use --dry-run for preview)"
+  ).requiredOption("--query <text>", "research prompt (required)").option(
+    "--apply",
+    "(deprecated; kept for backward compat \u2014 research spawns immediately by default)"
+  ).option("--dry-run", "preview only \u2014 do not spawn subagent (opt-in for advanced users)").option("--non-interactive", "skip all prompts (CI / scripts) \u2014 requires --apply or --dry-run").option("--model <model>", "subagent model: 'haiku' | 'sonnet' | 'opus'").action(async (raw) => {
     validateNonInteractiveFlags(raw, "research --query <text>");
     if (!raw.query) {
       console.error("error: --query <text> is required");
       process.exit(2);
     }
     const taskCtx = { task: raw.query, task_type: "search" };
-    if (raw.dryRun === true || !raw.apply && !raw.nonInteractive) {
+    if (raw.dryRun === true) {
       const preview = await runRouting(taskCtx, {
         skillsRoot: void 0,
         // Stub spawn — dry-run never reaches it; explicit COMPLETE keeps shape happy.
@@ -4458,7 +4702,9 @@ function registerResearch(program2) {
       }
       console.log(`[dry-run] matched_rule: ${preview.matchedRule?.id ?? "(fallback supervisor)"}`);
       console.log(`[dry-run] query: ${raw.query}`);
-      console.log("  (use --apply to spawn the subagent and emit verbatim COMPLETE round-trip)");
+      console.log(
+        "  (run without --dry-run to spawn the subagent and emit verbatim COMPLETE round-trip)"
+      );
       process.exit(0);
     }
     const result = await runRouting(taskCtx, {
@@ -4562,6 +4808,82 @@ function registerRollback(program2) {
   });
 }
 init_checkAgentTeams();
+var FLAT_LEGACY_DEPRECATED = /* @__PURE__ */ new Set(["plan-feature", "execute-task", "verify-work"]);
+var FLAT_LEGACY_KEEP = /* @__PURE__ */ new Set(["research", "retro"]);
+var NON_WORKFLOW_DIRS = /* @__PURE__ */ new Set(["disciplines", "judgments"]);
+async function scanWorkflowsNested(workflowsDir, entries) {
+  const workflows = [];
+  const deprecated = [];
+  for (const entry of entries.sort()) {
+    if (NON_WORKFLOW_DIRS.has(entry)) continue;
+    const src = join(workflowsDir, entry);
+    let s;
+    try {
+      s = await stat(src);
+    } catch {
+      continue;
+    }
+    if (!s.isDirectory()) continue;
+    let hasFlatSkill = false;
+    try {
+      await stat(join(src, "SKILL.md"));
+      hasFlatSkill = true;
+    } catch {
+      hasFlatSkill = false;
+    }
+    if (hasFlatSkill) {
+      if (FLAT_LEGACY_DEPRECATED.has(entry)) {
+        deprecated.push(entry);
+        continue;
+      }
+      if (FLAT_LEGACY_KEEP.has(entry)) {
+        workflows.push({ name: entry, relPath: entry, isMaster: false });
+        continue;
+      }
+      workflows.push({ name: entry, relPath: entry, isMaster: false });
+      continue;
+    }
+    let subEntries;
+    try {
+      subEntries = await readdir(src);
+    } catch {
+      continue;
+    }
+    for (const sub of subEntries.sort()) {
+      const subDir = join(src, sub);
+      let ss;
+      try {
+        ss = await stat(subDir);
+      } catch {
+        continue;
+      }
+      if (!ss.isDirectory()) continue;
+      try {
+        await stat(join(subDir, "SKILL.md"));
+      } catch {
+        continue;
+      }
+      const name = sub === "auto" ? entry : `${entry}-${sub}`;
+      workflows.push({ name, relPath: `${entry}/${sub}`, isMaster: sub === "auto" });
+    }
+  }
+  return { workflows, deprecated };
+}
+function renderDeprecationBlock(deprecated) {
+  if (deprecated.length === 0) return "";
+  return [
+    "\u26A0\uFE0F v3.0 BREAKING \u2014 v2 legacy slash cmd deprecated:",
+    "  /plan-feature   \u2192 /plan (master) | /plan-phase (sub)",
+    "  /execute-task   \u2192 /task (master) | /task-{clarify,code,test,deliver} (sub)",
+    "  /verify-work    \u2192 /verify (master) | /verify-{progress,paranoid,qa,security,design,simplify,multispec} (sub)",
+    "  /research, /retro \u4E0D\u53D8",
+    "  \u8BE6\u89C1 CHANGELOG [3.0.0]",
+    `  skipped install: ${deprecated.sort().join(", ")}`,
+    ""
+  ].join("\n");
+}
+
+// src/cli/lib/setup-helpers.ts
 var PHASE_212 = /* @__PURE__ */ new Set([
   "cc-plugin-marketplace",
   "git-clone-with-setup",
@@ -4581,18 +4903,7 @@ async function warnIfAgentTeamsMissing() {
   );
 }
 async function scanWorkflowsWithSkill(workflowsDir, entries) {
-  const out = [];
-  for (const entry of entries.sort()) {
-    const src = join(workflowsDir, entry);
-    try {
-      const s = await stat(src);
-      if (!s.isDirectory()) continue;
-      await stat(join(src, "SKILL.md"));
-      out.push(entry);
-    } catch {
-    }
-  }
-  return out;
+  return scanWorkflowsNested(workflowsDir, entries);
 }
 async function runStepBInstall(manifestPaths) {
   const opts = {
@@ -4678,7 +4989,12 @@ function registerSetup(program2) {
       console.error(`error: workflows directory not found at ${workflowsDir}`);
       process.exit(1);
     }
-    const toInstall = await scanWorkflowsWithSkill(workflowsDir, entries);
+    const { workflows: toInstall, deprecated } = await scanWorkflowsWithSkill(
+      workflowsDir,
+      entries
+    );
+    const depBlock = renderDeprecationBlock(deprecated);
+    if (depBlock) console.log(depBlock);
     if (toInstall.length === 0) {
       console.log("setup: no workflow directories with SKILL.md found \u2014 nothing to install");
       process.exit(2);
@@ -4687,22 +5003,24 @@ function registerSetup(program2) {
       console.log(
         `[dry-run] setup would install ${toInstall.length} workflow(s) to ${skillsBase}:`
       );
-      for (const name of toInstall) {
-        console.log(`  ${name}  \u2192  ${join(skillsBase, name)}`);
+      for (const wf of toInstall) {
+        const masterTag = wf.isMaster ? " (master)" : "";
+        console.log(`  ${wf.name}  \u2192  ${join(skillsBase, wf.name)}${masterTag}`);
       }
       console.log(`  run without --dry-run to execute`);
       process.exit(0);
     }
     let skillsInstalled = 0;
-    for (const name of toInstall) {
-      const src = join(workflowsDir, name);
-      const dst = join(skillsBase, name);
+    for (const wf of toInstall) {
+      const src = join(workflowsDir, wf.relPath);
+      const dst = join(skillsBase, wf.name);
       try {
         await cp(src, dst, { recursive: true, force: true });
-        console.log(`  [A] installed  ${name}  \u2192  ${dst}`);
+        const masterTag = wf.isMaster ? " (master)" : "";
+        console.log(`  [A] installed  ${wf.name}  \u2192  ${dst}${masterTag}`);
         skillsInstalled++;
       } catch (e) {
-        console.error(`  error: failed to copy ${name}: ${e.message}`);
+        console.error(`  error: failed to copy ${wf.name}: ${e.message}`);
         process.exit(1);
       }
     }
@@ -4963,7 +5281,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((resolve8) => {
+  const result = await new Promise((resolve9) => {
     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) => {
@@ -4971,15 +5289,15 @@ var uninstallNpmCli = async (ctx) => {
     });
     const timer = setTimeout(() => {
       child.kill("SIGKILL");
-      resolve8({ exitCode: -1, stderr: `${stderr}[timeout]` });
+      resolve9({ exitCode: -1, stderr: `${stderr}[timeout]` });
     }, 3e4);
     child.on("error", (e) => {
       clearTimeout(timer);
-      resolve8({ exitCode: -1, stderr: e.message });
+      resolve9({ exitCode: -1, stderr: e.message });
     });
     child.on("close", (code) => {
       clearTimeout(timer);
-      resolve8({ exitCode: code ?? -1, stderr });
+      resolve9({ exitCode: code ?? -1, stderr });
     });
   });
   if (result.exitCode !== 0) {
@@ -5029,12 +5347,12 @@ async function runUninstall(manifest, opts) {
 
 // src/cli/uninstall.ts
 function registerUninstall(program2) {
-  program2.command("uninstall <name>").description("Uninstall an upstream (dry-run by default \u2014 pass --apply to execute)").option("--apply", "execute the uninstall (default: dry-run preview only)").option("--dry-run", "force dry-run (overrides --apply if both are set)").option("--yes", "skip interactive confirm \u2014 requires --apply (CI / scripts)").option("--non-interactive", "alias for --yes (CI compat)").action(async (name, raw) => {
+  program2.command("uninstall <name>").description("Uninstall an upstream (immediate by default \u2014 use --dry-run for preview)").option("--apply", "(deprecated; kept for backward compat \u2014 uninstall is immediate by default)").option("--dry-run", "preview only \u2014 do not delete files (opt-in for advanced users)").option("--yes", "skip interactive confirm (CI / scripts) \u2014 fatal with --dry-run").option("--non-interactive", "alias for --yes (CI compat)").action(async (name, raw) => {
     const yes = raw.yes === true || raw.nonInteractive === true;
-    if (yes && !raw.apply) {
+    if (yes && raw.dryRun) {
       console.error(
-        `error: --yes requires --apply to execute
-  fix:  harnessed uninstall ${name} --yes --apply`
+        `error: --yes is incompatible with --dry-run (dry-run does not mutate)
+  fix:  harnessed uninstall ${name} --yes  (immediate) OR harnessed uninstall ${name} --dry-run  (preview)`
       );
       process.exit(2);
     }
@@ -5065,10 +5383,10 @@ function registerUninstall(program2) {
       process.exit(1);
     }
     const method = v.manifest.spec.install.method;
-    const dryRun = raw.dryRun === true || !raw.apply;
+    const dryRun = raw.dryRun === true;
     if (dryRun) {
       console.log(`[dry-run] would uninstall '${resolvedName}' via method '${method}'`);
-      console.log(`  run with --apply to execute`);
+      console.log(`  run without --dry-run to execute`);
       process.exit(2);
     }
     if (!yes) {