harnessed 3.4.2 → 3.4.4

package/dist/index.mjs

@@ -1,6 +1,6 @@
 // package.json
 var package_default = {
-  version: "3.4.2"};
+  version: "3.4.4"};
 
 // src/index.ts
 var VERSION = package_default.version;

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../package.json","../src/index.ts"],"names":[],"mappings":";AAAA,IAAA,eAAA,GAAA;AAAA,EAEE,OAAA,EAAW,OA8Fb,CAAA;;;AC3FO,IAAM,UAAU,eAAA,CAAI","file":"index.mjs","sourcesContent":["{\n  \"name\": \"harnessed\",\n  \"version\": \"3.4.2\",\n  \"description\": \"AI coding harness package manager + composition orchestrator\",\n  \"type\": \"module\",\n  \"license\": \"Apache-2.0\",\n  \"author\": \"easyinplay\",\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"https://github.com/easyinplay/harnessed.git\"\n  },\n  \"homepage\": \"https://github.com/easyinplay/harnessed#readme\",\n  \"bugs\": \"https://github.com/easyinplay/harnessed/issues\",\n  \"keywords\": [\n    \"claude-code\",\n    \"ai-harness\",\n    \"package-manager\",\n    \"composition\",\n    \"skill-pack\",\n    \"mcp\",\n    \"orchestrator\"\n  ],\n  \"engines\": {\n    \"node\": \">=22.0.0\"\n  },\n  \"packageManager\": \"pnpm@10.12.0\",\n  \"bin\": {\n    \"harnessed\": \"./dist/cli.mjs\"\n  },\n  \"main\": \"./dist/index.mjs\",\n  \"types\": \"./dist/index.d.ts\",\n  \"exports\": {\n    \".\": {\n      \"types\": \"./dist/index.d.ts\",\n      \"import\": \"./dist/index.mjs\",\n      \"default\": \"./dist/index.mjs\"\n    },\n    \"./schemas\": {\n      \"types\": \"./dist/schemas/index.d.ts\",\n      \"import\": \"./dist/schemas/index.mjs\"\n    },\n    \"./package.json\": \"./package.json\"\n  },\n  \"files\": [\n    \"dist\",\n    \"manifests\",\n    \"workflows\",\n    \"routing\",\n    \"config-templates\",\n    \"schemas\",\n    \"README.md\",\n    \"LICENSE\",\n    \"NOTICE\"\n  ],\n  \"scripts\": {\n    \"dev\": \"tsup --watch\",\n    \"build\": \"tsc --noEmit && tsup\",\n    \"build:schema\": \"node ./scripts/build-schema.mjs\",\n    \"validate:schema\": \"node ./scripts/validate-schema.mjs\",\n    \"typecheck\": \"tsc --noEmit\",\n    \"test\": \"vitest run --passWithNoTests\",\n    \"test:watch\": \"vitest\",\n    \"test:coverage\": \"vitest run --coverage --passWithNoTests\",\n    \"bench\": \"vitest bench --run\",\n    \"lint\": \"biome check .\",\n    \"lint:fix\": \"biome check --write .\",\n    \"format\": \"biome format --write .\"\n  },\n  \"dependencies\": {\n    \"@anthropic-ai/claude-agent-sdk\": \"0.3.142\",\n    \"@clack/prompts\": \"^0.10.1\",\n    \"@sinclair/typebox\": \"^0.34.49\",\n    \"ajv\": \"^8.20.0\",\n    \"ajv-errors\": \"^3.0.0\",\n    \"ajv-formats\": \"^3.0.1\",\n    \"commander\": \"^13.0.0\",\n    \"diff\": \"^9.0.0\",\n    \"expr-eval\": \"^2.0.2\",\n    \"picocolors\": \"^1.1.1\",\n    \"proper-lockfile\": \"^4.1.2\",\n    \"yaml\": \"^2.9.0\"\n  },\n  \"devDependencies\": {\n    \"@biomejs/biome\": \"^2.0.0\",\n    \"@types/node\": \"^22.10.0\",\n    \"@types/proper-lockfile\": \"^4.1.4\",\n    \"@vitest/coverage-v8\": \"^4.0.0\",\n    \"tsup\": \"^8.3.0\",\n    \"typescript\": \"^5.6.0\",\n    \"vitest\": \"^4.0.0\"\n  },\n  \"pnpm\": {\n    \"onlyBuiltDependencies\": [\n      \"esbuild\"\n    ]\n  }\n}\n","// Main library entry — re-exports public APIs.\n// phase 1.1 batch 1: skeleton only; schema validator wired in batch 2 (T3+).\n\nimport pkg from '../package.json' with { type: 'json' }\n\nexport const VERSION = pkg.version\n"]}
+{"version":3,"sources":["../package.json","../src/index.ts"],"names":[],"mappings":";AAAA,IAAA,eAAA,GAAA;AAAA,EAEE,OAAA,EAAW,OA8Fb,CAAA;;;AC3FO,IAAM,UAAU,eAAA,CAAI","file":"index.mjs","sourcesContent":["{\n  \"name\": \"harnessed\",\n  \"version\": \"3.4.4\",\n  \"description\": \"AI coding harness package manager + composition orchestrator\",\n  \"type\": \"module\",\n  \"license\": \"Apache-2.0\",\n  \"author\": \"easyinplay\",\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"https://github.com/easyinplay/harnessed.git\"\n  },\n  \"homepage\": \"https://github.com/easyinplay/harnessed#readme\",\n  \"bugs\": \"https://github.com/easyinplay/harnessed/issues\",\n  \"keywords\": [\n    \"claude-code\",\n    \"ai-harness\",\n    \"package-manager\",\n    \"composition\",\n    \"skill-pack\",\n    \"mcp\",\n    \"orchestrator\"\n  ],\n  \"engines\": {\n    \"node\": \">=22.0.0\"\n  },\n  \"packageManager\": \"pnpm@10.12.0\",\n  \"bin\": {\n    \"harnessed\": \"./dist/cli.mjs\"\n  },\n  \"main\": \"./dist/index.mjs\",\n  \"types\": \"./dist/index.d.ts\",\n  \"exports\": {\n    \".\": {\n      \"types\": \"./dist/index.d.ts\",\n      \"import\": \"./dist/index.mjs\",\n      \"default\": \"./dist/index.mjs\"\n    },\n    \"./schemas\": {\n      \"types\": \"./dist/schemas/index.d.ts\",\n      \"import\": \"./dist/schemas/index.mjs\"\n    },\n    \"./package.json\": \"./package.json\"\n  },\n  \"files\": [\n    \"dist\",\n    \"manifests\",\n    \"workflows\",\n    \"routing\",\n    \"config-templates\",\n    \"schemas\",\n    \"README.md\",\n    \"LICENSE\",\n    \"NOTICE\"\n  ],\n  \"scripts\": {\n    \"dev\": \"tsup --watch\",\n    \"build\": \"tsc --noEmit && tsup\",\n    \"build:schema\": \"node ./scripts/build-schema.mjs\",\n    \"validate:schema\": \"node ./scripts/validate-schema.mjs\",\n    \"typecheck\": \"tsc --noEmit\",\n    \"test\": \"vitest run --passWithNoTests\",\n    \"test:watch\": \"vitest\",\n    \"test:coverage\": \"vitest run --coverage --passWithNoTests\",\n    \"bench\": \"vitest bench --run\",\n    \"lint\": \"biome check .\",\n    \"lint:fix\": \"biome check --write .\",\n    \"format\": \"biome format --write .\"\n  },\n  \"dependencies\": {\n    \"@anthropic-ai/claude-agent-sdk\": \"0.3.142\",\n    \"@clack/prompts\": \"^0.10.1\",\n    \"@sinclair/typebox\": \"^0.34.49\",\n    \"ajv\": \"^8.20.0\",\n    \"ajv-errors\": \"^3.0.0\",\n    \"ajv-formats\": \"^3.0.1\",\n    \"commander\": \"^13.0.0\",\n    \"diff\": \"^9.0.0\",\n    \"expr-eval\": \"^2.0.2\",\n    \"picocolors\": \"^1.1.1\",\n    \"proper-lockfile\": \"^4.1.2\",\n    \"yaml\": \"^2.9.0\"\n  },\n  \"devDependencies\": {\n    \"@biomejs/biome\": \"^2.0.0\",\n    \"@types/node\": \"^22.10.0\",\n    \"@types/proper-lockfile\": \"^4.1.4\",\n    \"@vitest/coverage-v8\": \"^4.0.0\",\n    \"tsup\": \"^8.3.0\",\n    \"typescript\": \"^5.6.0\",\n    \"vitest\": \"^4.0.0\"\n  },\n  \"pnpm\": {\n    \"onlyBuiltDependencies\": [\n      \"esbuild\"\n    ]\n  }\n}\n","// Main library entry — re-exports public APIs.\n// phase 1.1 batch 1: skeleton only; schema validator wired in batch 2 (T3+).\n\nimport pkg from '../package.json' with { type: 'json' }\n\nexport const VERSION = pkg.version\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harnessed",
-  "version": "3.4.2",
+  "version": "3.4.4",
   "description": "AI coding harness package manager + composition orchestrator",
   "type": "module",
   "license": "Apache-2.0",

package/workflows/auto/SKILL.md

@@ -103,6 +103,21 @@ Sister `workflows/capabilities.yaml`:
 - 4 stage-master `/discuss /plan /task /verify` 仍可独立 invoke — `/auto` 是 opt-in NEW workflow
 - `--staged` opt-in for stage gate UX (每 stage 完停 user review)
 
+## How to invoke
+
+Use the Bash tool to run:
+
+```bash
+echo "$ARGUMENTS" | harnessed run auto --task-stdin
+```
+
+If `$ARGUMENTS` is empty, run `harnessed run auto` (no stdin pipe).
+
+After completion, the Bash output prints a `Next:` hint on stderr suggesting the next stage. Decide whether to invoke based on conversation context — the hint is informational, not prescriptive.
+- For stage-by-stage review, append `--staged` (pauses between stages for user review).
+
+<!-- harnessed-generated:v3.4.4 -->
+
 ## References
 
 - D-01 master orchestrator delegation pattern

package/workflows/capabilities.yaml

@@ -451,7 +451,7 @@ capabilities:
     since: v2.0
     category: tool-bundled-skill
     description: Sub-task completion gate (verbatim COMPLETE; max-iterations fallback)
-    sdk_ref: src/routing/lib/ralphLoop.ts
+    sdk_ref: src/workflow/lib/ralphLoop.ts
     fires_when:
       - subtask.completion_required == true
 

package/workflows/discuss/auto/SKILL.md

@@ -5,7 +5,7 @@ description: |
   战略层 / Phase 层 / 子任务层独立判断 gate, 可能 3 个全跑 / 1-2 个 / 全跳 + 透明声明。
   schema_version: harnessed.workflow.v3 with delegates_to (3 sub: strategic + phase + subtask, mode parallel)
   + disciplines_applied (6 default) + tools_available (planning-with-files)。
-  Triggered by harnessed CLI `harnessed discuss --topic <text>` or slash command `/discuss`
+  Triggered by slash command `/discuss`
   (bare per ADR 0030 namespace policy D-02 LOCK) after `harnessed setup`.
 trigger_phrases:
   - "discuss"
@@ -49,9 +49,22 @@ Sister `workflows/capabilities.yaml`:
 
 ## Invocation
 
-- CLI: `harnessed discuss --topic "<text>"`
 - Slash command: `/discuss <text>` (bare per ADR 0030 namespace policy D-02 LOCK after `harnessed setup`)
 
+## How to invoke
+
+Use the Bash tool to run:
+
+```bash
+echo "$ARGUMENTS" | harnessed run discuss --task-stdin
+```
+
+If `$ARGUMENTS` is empty, run `harnessed run discuss` (no stdin pipe).
+
+After completion, the Bash output prints a `Next:` hint on stderr suggesting the next stage. Decide whether to invoke based on conversation context — the hint is informational, not prescriptive.
+
+<!-- harnessed-generated:v3.4.4 -->
+
 ## References
 
 - D-01 master orchestrator delegation pattern

package/workflows/discuss/phase/SKILL.md

@@ -41,7 +41,6 @@ Sister `workflows/judgments/phase-gate.yaml`:
 
 ## Invocation
 
-- CLI: `harnessed discuss-phase --phase <num>`
 - Slash command: `/discuss-phase <num>` (after `harnessed setup`)
 
 ## Routing rules
@@ -54,14 +53,17 @@ Sister `workflows/judgments/phase-gate.yaml`:
 
 ## How to invoke
 
-Use the SlashCommand tool to run: `{{ capabilities.gsd-discuss-phase.cmd }}`
+Use the Bash tool to run:
 
-(If a `⚠️ ... not installed` warning was printed by `harnessed setup`, the backing
-capability is missing on disk. Install it (`claude plugin install <name>` for
-plugins, or follow the official install instructions for user-skills — e.g. for
-gstack: `git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack` then
-`cd ~/.claude/skills/gstack && ./setup`), then re-run `harnessed setup` to re-render
-this SKILL.md and clear the warning.)
+```bash
+echo "$ARGUMENTS" | harnessed run discuss-phase --task-stdin
+```
+
+If `$ARGUMENTS` is empty, run `harnessed run discuss-phase` (no stdin pipe).
+
+After completion, the Bash output prints a `Next:` hint on stderr suggesting the next stage. Decide whether to invoke based on conversation context — the hint is informational, not prescriptive.
+
+<!-- harnessed-generated:v3.4.4 -->
 
 ## References
 

package/workflows/discuss/strategic/SKILL.md

@@ -6,7 +6,7 @@ description: |
   schema_version: harnessed.workflow.v3 with disciplines_applied (6 default) + tools_available
   (gstack-office-hours + gstack-plan-ceo-review + planning-with-files) + 3 phases (gate
   judgments.strategic-gate.* fires + planning-with-files /plan findings.md 持久化)。
-  Triggered by harnessed CLI `harnessed discuss-strategic --topic <text>` or slash command
+  Triggered by slash command
   `/discuss-strategic` after `harnessed setup`.
 trigger_phrases:
   - "discuss strategic"
@@ -45,7 +45,6 @@ Sister `workflows/judgments/strategic-gate.yaml`:
 
 ## Invocation
 
-- CLI: `harnessed discuss-strategic --topic "<text>"`
 - Slash command: `/discuss-strategic <text>` (after `harnessed setup`)
 
 ## Routing rules
@@ -58,14 +57,17 @@ Sister `workflows/judgments/strategic-gate.yaml`:
 
 ## How to invoke
 
-Use the SlashCommand tool to run: `{{ capabilities.gstack-office-hours.cmd }}`
+Use the Bash tool to run:
 
-(If a `⚠️ ... not installed` warning was printed by `harnessed setup`, the backing
-capability is missing on disk. Install it (`claude plugin install <name>` for
-plugins, or follow the official install instructions for user-skills — e.g. for
-gstack: `git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack` then
-`cd ~/.claude/skills/gstack && ./setup`), then re-run `harnessed setup` to re-render
-this SKILL.md and clear the warning.)
+```bash
+echo "$ARGUMENTS" | harnessed run discuss-strategic --task-stdin
+```
+
+If `$ARGUMENTS` is empty, run `harnessed run discuss-strategic` (no stdin pipe).
+
+After completion, the Bash output prints a `Next:` hint on stderr suggesting the next stage. Decide whether to invoke based on conversation context — the hint is informational, not prescriptive.
+
+<!-- harnessed-generated:v3.4.4 -->
 
 ## References
 

package/workflows/discuss/subtask/SKILL.md

@@ -46,7 +46,6 @@ Sister `workflows/judgments/subtask-gate.yaml`:
 
 ## Invocation
 
-- CLI: `harnessed discuss-subtask --task "<text>"`
 - Slash command: `/discuss-subtask <text>` (after `harnessed setup`)
 
 ## Routing rules
@@ -59,14 +58,17 @@ Sister `workflows/judgments/subtask-gate.yaml`:
 
 ## How to invoke
 
-Use the SlashCommand tool to run: `{{ capabilities.superpowers-brainstorming.cmd }}`
+Use the Bash tool to run:
 
-(If a `⚠️ ... not installed` warning was printed by `harnessed setup`, the backing
-capability is missing on disk. Install it (`claude plugin install <name>` for
-plugins, or follow the official install instructions for user-skills — e.g. for
-gstack: `git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack` then
-`cd ~/.claude/skills/gstack && ./setup`), then re-run `harnessed setup` to re-render
-this SKILL.md and clear the warning.)
+```bash
+echo "$ARGUMENTS" | harnessed run discuss-subtask --task-stdin
+```
+
+If `$ARGUMENTS` is empty, run `harnessed run discuss-subtask` (no stdin pipe).
+
+After completion, the Bash output prints a `Next:` hint on stderr suggesting the next stage. Decide whether to invoke based on conversation context — the hint is informational, not prescriptive.
+
+<!-- harnessed-generated:v3.4.4 -->
 
 ## References
 

package/workflows/execute-task/SKILL.md

@@ -38,10 +38,11 @@ v2 schema fields per `src/workflow/schema/workflow.ts` (T2.4.W0.1 16th surface
 - `parallelism: judgments.parallelism-gate.<route>.fires` (D-11 subagent / Agent Teams / main session route)
 - `fallback.max_iterations_exceeded: {action, message, exit_code}` (R20.10 acceptance c "explicit NOT silent")
 
-Per-phase models load from `workflows/execute-task/phases.yaml`; engine.runRouting
-spawns each phase as a sub-agent via `@anthropic-ai/claude-agent-sdk` 0.3.142+
+Per-phase models load from `workflows/execute-task/workflow.yaml` (v3 SoT post
+v3.4.4 Phase 6 — v2 phases.yaml deleted); runWorkflow spawns each phase as a
+sub-agent via `@anthropic-ai/claude-agent-sdk` 0.3.142+
 (`AgentDefinition` 5-字段 unpack — ADR 0011 § 4). ralph-loop SDK wrapper at 04-deliver
-reuses sister Phase 2.2 v0.2.0 ship: `src/routing/lib/ralphLoop.ts` (54L) + `sdkSpawn.ts` (91L)
+reuses sister Phase 2.2 v0.2.0 ship: `src/workflow/lib/ralphLoop.ts` (54L) + `sdkSpawn.ts` (91L)
 + 4-layer dual-signal `isComplete` (NOT 重写 — per RESEARCH § 3.1).
 
 ## CLI invocation (the only enforced entry — B-28)
@@ -78,6 +79,6 @@ the CLI subcommand above (B-28 single-entry contract).
 - ADR 0011 — execute-task SDK + ralph-loop integration (phase 2.2 W6 — finalize)
 - `.planning/intel/omc-comparison.md` § CD-2 — per-phase model tier defaults
 - `src/cli/execute-task.ts` — CLI implementation (T5.1)
-- `workflows/execute-task/phases.yaml` — 4-phase config (T3.3)
-- `src/routing/lib/sdkSpawn.ts` — SDK query() consumer (T4.1)
-- `src/routing/lib/ralphLoop.ts` — verbatim COMPLETE round-trip
+- `workflows/execute-task/workflow.yaml` — 4-phase config (v3 SoT; v3.4.4 Phase 6 ship — v2 phases.yaml deleted)
+- `src/workflow/lib/sdkSpawn.ts` — SDK query() consumer (T4.1)
+- `src/workflow/lib/ralphLoop.ts` — verbatim COMPLETE round-trip

package/workflows/execute-task/workflow.yaml

@@ -0,0 +1,93 @@
+# workflows/execute-task/workflow.yaml — v3.4.4 Phase 4 Commit 1 NEW (Path A)
+# Former v2 `phases.yaml` (74L) deleted v3.4.4 Phase 6 Wave 3c — this v3
+# workflow.yaml is now the single SoT. Authored fresh per HANDOFF-v3.4.4 L745
+# Path A decision + PHASE-4-SPEC L101-180 verbatim.
+#
+# 4-phase chain mirrors v2 verbatim:
+#   01-clarify  superpowers-brainstorming  opus    gate: subtask-gate.brainstorming.fires
+#   02-code     karpathy 心法 + on[]       sonnet  conditional: tdd / grill-with-docs / zoom-out
+#   03-test     superpowers TDD            sonnet  on: test_fail → diagnose
+#   04-deliver  ralph-loop                 haiku   args.completion_promise=COMPLETE + fallback
+#
+# v2 → v3 字段 delta (PHASE-4-SPEC L13 + L116-178):
+#   BUMP `schema_version: harnessed.workflow.v3` (sister Phase 3.3 W0.5 WorkflowSchemaV3)
+#   ADD  `disciplines_applied: [6 basename]` (D-09 L0 Discipline Substrate, Pattern A A.1 strict Literal Union)
+#   ADD  `tools_available: [7 capabilities.yaml entry name]` (D-05 Contract C1 cross-validate)
+#   KEEP phases verbatim from former v2 phases.yaml (Path A1 — coexisted through Phase 5; v2 deleted Phase 6 Wave 3c)
+#
+# Per-phase model tier (intel CD-2 § 第 4 条) preserved verbatim from v2:
+#   opus / sonnet / sonnet / haiku
+# Override via CLI: `--model-tier inherit` (B-10 escape hatch).
+#
+# Sister refs:
+#   - .planning/v3.4.4/PHASE-4-SPEC.md L101-180 (NEW yaml shape verbatim)
+#   - workflows/execute-task/phases.yaml (former v2 SoT — DELETED v3.4.4 Phase 6 Wave 3c; this workflow.yaml is sole SoT)
+#   - workflows/research/workflow.yaml (v3 standalone shape reference)
+#   - workflows/verify/simplify/workflow.yaml (v3 sub-workflow shape reference)
+#   - workflows/capabilities.yaml (7 capability refs: superpowers-brainstorming/tdd/grill-with-docs/zoom-out/diagnose/ralph-loop/planning-with-files)
+#   - workflows/defaults.yaml ralph_max_iterations.execute-task.{01..04}
+#   - workflows/disciplines/{karpathy,output-style,language,operational,priority,protocols}.yaml (L0 substrate)
+#   - src/workflow/schema/workflow.ts WorkflowSchemaV3 (Phase 3.3 W0.5 SHIPPED 122L)
+
+schema_version: harnessed.workflow.v3
+workflow: execute-task
+description: |
+  子任务执行 workflow — 4-phase chain (brainstorming → karpathy + mattpocock route by
+  condition → TDD + diagnose → ralph-loop COMPLETE) triggered by harnessed CLI
+  `harnessed execute-task --task <text>` OR universal `harnessed run execute-task`.
+
+disciplines_applied: [karpathy, output-style, language, operational, priority, protocols]
+tools_available: [superpowers-brainstorming, tdd, grill-with-docs, zoom-out, diagnose, ralph-loop, planning-with-files]
+
+phases:
+  - id: 01-clarify
+    name: brainstorming
+    upstream: superpowers brainstorming
+    capability: '{{ capabilities.superpowers-brainstorming.cmd }}'
+    model: opus
+    max_iterations: '{{ defaults.ralph_max_iterations.execute-task.01-clarify }}'
+    gate: judgments.subtask-gate.brainstorming.fires
+
+  - id: 02-code
+    name: code (karpathy 心法 always-on + mattpocock conditional route)
+    upstream: karpathy
+    model: sonnet
+    max_iterations: '{{ defaults.ralph_max_iterations.execute-task.02-code }}'
+    on:
+      - if: 'judgments.tdd-gate.tdd-strongly-suggested.fires'
+        invoke: '{{ capabilities.tdd.cmd }}'
+      - if: 'phase.spec_ambiguous == true'
+        invoke: '{{ capabilities.grill-with-docs.cmd }}'
+      - if: 'phase.unfamiliar_module == true'
+        invoke: '{{ capabilities.zoom-out.cmd }}'
+
+  - id: 03-test
+    name: test (conditional TDD + diagnose on fail)
+    upstream: superpowers TDD
+    capability: '{{ capabilities.tdd.cmd }}'
+    model: sonnet
+    max_iterations: '{{ defaults.ralph_max_iterations.execute-task.03-test }}'
+    on:
+      - if: 'test_fail == true'
+        invoke: '{{ capabilities.diagnose.cmd }}'
+
+  - id: 04-deliver
+    name: deliver (ralph-loop COMPLETE gate + max-iter fallback)
+    upstream: ralph-loop
+    capability: '{{ capabilities.ralph-loop.cmd }}'
+    model: haiku
+    args:
+      completion_promise: COMPLETE
+      max_iterations: '{{ defaults.ralph_max_iterations.execute-task.04-deliver }}'
+    gate: judgments.parallelism-gate.fires
+    parallelism: judgments.parallelism-gate.ralph-loop-wrapper.fires
+    on:
+      - if: 'subtask.lines >= 20 and subtask.type != "single_command_query"'
+        invoke: '{{ capabilities.ralph-loop.cmd }}'
+      - if: 'subtask.lines < 20 or subtask.type == "single_command_query"'
+        action: skip
+    fallback:
+      max_iterations_exceeded:
+        action: emit_warning_and_halt
+        message: '⚠️ ralph-loop max-iterations ({{ args.max_iterations }}) exceeded for execute-task 04-deliver. Sub-task likely incomplete — see workflow engine catch handler for manual options.'
+        exit_code: 1

package/workflows/plan/architecture/SKILL.md

@@ -42,7 +42,6 @@ trigger `is-complex-architecture` 重构 ref。
 
 ## Invocation
 
-- CLI: `harnessed plan-architecture --module "<name>"`
 - Slash command: `/plan-architecture <name>` (after `harnessed setup`)
 
 ## Routing rules
@@ -55,14 +54,17 @@ trigger `is-complex-architecture` 重构 ref。
 
 ## How to invoke
 
-Use the SlashCommand tool to run: `{{ capabilities.plan-eng-review.cmd }}`
+Use the Bash tool to run:
 
-(If a `⚠️ ... not installed` warning was printed by `harnessed setup`, the backing
-capability is missing on disk. Install it (`claude plugin install <name>` for
-plugins, or follow the official install instructions for user-skills — e.g. for
-gstack: `git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack` then
-`cd ~/.claude/skills/gstack && ./setup`), then re-run `harnessed setup` to re-render
-this SKILL.md and clear the warning.)
+```bash
+echo "$ARGUMENTS" | harnessed run plan-architecture --task-stdin
+```
+
+If `$ARGUMENTS` is empty, run `harnessed run plan-architecture` (no stdin pipe).
+
+After completion, the Bash output prints a `Next:` hint on stderr suggesting the next stage. Decide whether to invoke based on conversation context — the hint is informational, not prescriptive.
+
+<!-- harnessed-generated:v3.4.4 -->
 
 ## References
 

package/workflows/plan/auto/SKILL.md

@@ -6,7 +6,7 @@ description: |
   task_plan.md。schema_version: harnessed.workflow.v3 with delegates_to (2 sub: architecture
   serial order 1 + phase serial order 2) + disciplines_applied (6 default) + tools_available
   (planning-with-files + plan-eng-review + gsd-plan-phase)。
-  Triggered by harnessed CLI `harnessed plan --topic <text>` or slash command `/plan`
+  Triggered by slash command `/plan`
   (bare per ADR 0030 namespace policy D-02 LOCK) after `harnessed setup`.
 trigger_phrases:
   - "plan"
@@ -50,9 +50,22 @@ Sister `workflows/capabilities.yaml`:
 
 ## Invocation
 
-- CLI: `harnessed plan --topic "<text>"`
 - Slash command: `/plan <text>` (bare per ADR 0030 namespace policy D-02 LOCK after `harnessed setup`)
 
+## How to invoke
+
+Use the Bash tool to run:
+
+```bash
+echo "$ARGUMENTS" | harnessed run plan --task-stdin
+```
+
+If `$ARGUMENTS` is empty, run `harnessed run plan` (no stdin pipe).
+
+After completion, the Bash output prints a `Next:` hint on stderr suggesting the next stage. Decide whether to invoke based on conversation context — the hint is informational, not prescriptive.
+
+<!-- harnessed-generated:v3.4.4 -->
+
 ## References
 
 - D-01 master orchestrator delegation pattern

package/workflows/plan/phase/SKILL.md

@@ -46,7 +46,6 @@ reframe)。
 
 ## Invocation
 
-- CLI: `harnessed plan-phase --phase <num>`
 - Slash command: `/plan-phase <num>` (after `harnessed setup`)
 
 ## Output artifacts
@@ -57,14 +56,17 @@ reframe)。
 
 ## How to invoke
 
-Use the SlashCommand tool to run: `{{ capabilities.gsd-plan-phase.cmd }}`
+Use the Bash tool to run:
 
-(If a `⚠️ ... not installed` warning was printed by `harnessed setup`, the backing
-capability is missing on disk. Install it (`claude plugin install <name>` for
-plugins, or follow the official install instructions for user-skills — e.g. for
-gstack: `git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack` then
-`cd ~/.claude/skills/gstack && ./setup`), then re-run `harnessed setup` to re-render
-this SKILL.md and clear the warning.)
+```bash
+echo "$ARGUMENTS" | harnessed run plan-phase --task-stdin
+```
+
+If `$ARGUMENTS` is empty, run `harnessed run plan-phase` (no stdin pipe).
+
+After completion, the Bash output prints a `Next:` hint on stderr suggesting the next stage. Decide whether to invoke based on conversation context — the hint is informational, not prescriptive.
+
+<!-- harnessed-generated:v3.4.4 -->
 
 ## References
 

package/workflows/research/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: research
-description: 多源调研 workflow — Tavily/Exa/ctx7 多源 fan-out + GSD discuss synth aggregate; harnessed v2.0 NEW per R20.7 (Stage ① Discuss 独立 call); schema bumped to harnessed.workflow.v3 in Phase v3.0-3.4 W1.1 (T3.4.W1.1) with disciplines_applied [6] + tools_available [tavily-mcp, exa-mcp, ctx7, gsd-discuss-phase], phases reuse v2 verbatim. Triggered by harnessed CLI `harnessed research --topic <text>` or slash command `/research` after `harnessed setup`.
+description: 多源调研 workflow — Tavily/Exa/ctx7 多源 fan-out + GSD discuss synth aggregate; harnessed v2.0 NEW per R20.7 (Stage ① Discuss 独立 call); schema bumped to harnessed.workflow.v3 in Phase v3.0-3.4 W1.1 (T3.4.W1.1) with disciplines_applied [6] + tools_available [tavily-mcp, exa-mcp, ctx7, gsd-discuss-phase], phases reuse v2 verbatim. Triggered by slash command `/research` after `harnessed setup`.
 preamble-tier: 2
 schema_version: harnessed.workflow.v3
 ---
@@ -28,7 +28,6 @@ Sister `workflows/capabilities.yaml` entries:
 - `gsd-discuss-phase` (synth aggregate)
 
 ## Invocation
-- CLI: `harnessed research --topic "<topic>"`
 - Slash command: `/research <topic>` (after `harnessed setup`)
 
 ## Routing rules (sister ~/.claude/rules/web-search.md)
@@ -37,3 +36,46 @@ Sister `workflows/capabilities.yaml` entries:
 - 库 / API 文档 → ctx7 CLI (per ~/.claude/rules/context7.md)
 - 关键词 / 时效内容 → Tavily MCP (默认)
 - 抓整站 / 站点结构 → Tavily crawl/map
+
+## How to invoke
+
+**Preferred path** (master orchestrator): dispatch to the per-sub-workflow slash commands in the order this stage prescribes. Each sub command lives at `~/.claude/commands/<sub-name>.md` with its own dual-path fallback.
+
+**Fallback path** (when the upstream isn't installed or returns no result): use the Task tool to spawn a general-purpose subagent with this prompt:
+
+> You are a **Research analyst**.
+>
+> **Mission**: Multi-source investigation (docs / web search / codebase grep / library probe) producing a `findings.md` with citations, NOT speculation. Use `ctx7` for library docs, `tavily-mcp` / `exa-mcp` for web, `gh` CLI for GitHub artifacts, and codebase `Grep` for internal references.
+>
+> **Default-suspect mode**: assume the change is broken / risky / incomplete until proven otherwise. Cite `file:line` for every finding; do not generalize.
+>
+> **Review checklist**:
+> 1. Resolve each unknown claim to a citable source (URL, file:line, or `ctx7` doc id)
+>
+> 2. Cite version explicitly when discussing library / framework APIs (training cutoff may be stale)
+>
+> 3. Capture conflicting sources side-by-side; do not silently pick one
+>
+> 4. Flag `OPEN: <question>` for items the user must decide; never paper over
+>
+> 5. Persist results to `.planning/<phase>/findings.md` for cross-session handoff
+>
+> **Output format**: structured report with severity-classified findings (verified / unverified / conflicting / open). One finding per line: `[severity] file:line — problem (one sentence); fix: suggested change`. If no findings, say so explicitly. No preamble, no end-of-report summary.
+
+(Role prompt is self-contained — works even when the upstream `specialist` user-skill / plugin isn't installed.)
+
+(Sister `~/.claude/commands/research.md` is also generated by `harnessed setup` so `/research` is a real platform slash command — both files carry the same dual-path instruction. Previous v3.4.x `harnessed research --apply` CLI claims are removed; that subcommand was never implemented.)
+
+## How to invoke
+
+Use the Bash tool to run:
+
+```bash
+echo "$ARGUMENTS" | harnessed run research --task-stdin
+```
+
+If `$ARGUMENTS` is empty, run `harnessed run research` (no stdin pipe).
+
+After completion, the Bash output prints a `Next:` hint on stderr suggesting the next stage. Decide whether to invoke based on conversation context — the hint is informational, not prescriptive.
+
+<!-- harnessed-generated:v3.4.4 -->

package/workflows/retro/SKILL.md

@@ -47,26 +47,19 @@ Sister `workflows/capabilities.yaml` entries:
 - ✅ **触发**: 项目结束 / 里程碑结束 / 用户明示 "复盘 / retro / lessons learned"
 - ❌ **跳过**: 日常 PR / 单 phase 完成 (常规 verify-progress 已够用)
 
-## CLI invocation
+## How to invoke
 
-```bash
-# Dry-run preview — arbitrate-only, never spawns SDK.
-harnessed retro --milestone <name> --dry-run --non-interactive
+Use the Bash tool to run:
 
-# Apply path — real SDK spawn + 2-phase serial (gstack /retro → planning-with-files RETROSPECTIVE.md sink).
-harnessed retro --milestone <name> --apply
+```bash
+echo "$ARGUMENTS" | harnessed run retro --task-stdin
 ```
 
-## How to invoke
+If `$ARGUMENTS` is empty, run `harnessed run retro` (no stdin pipe).
 
-Use the SlashCommand tool to run: `{{ capabilities.retro-gstack.cmd }}`
+After completion, the Bash output prints a `Next:` hint on stderr suggesting the next stage. Decide whether to invoke based on conversation context — the hint is informational, not prescriptive.
 
-(If a `⚠️ ... not installed` warning was printed by `harnessed setup`, the backing
-capability is missing on disk. Install it (`claude plugin install <name>` for
-plugins, or follow the official install instructions for user-skills — e.g. for
-gstack: `git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack` then
-`cd ~/.claude/skills/gstack && ./setup`), then re-run `harnessed setup` to re-render
-this SKILL.md and clear the warning.)
+<!-- harnessed-generated:v3.4.4 -->
 
 ## References