flower-trellis 0.5.0-beta.5 → 0.5.0-beta.6

package/enhancements/0.6/overrides/bundles/intent-routing.json

@@ -6,6 +6,7 @@
   "patches": [
     "workflow/hub",
     "workflow/phase-ownership",
+    "workflow/task-brief-review",
     "workflow/state-no-task",
     "workflow/state-missing-task",
     "workflow/runtime-contract-reference",
@@ -25,6 +26,8 @@
     "hooks/claude-session-start/missing-task-routing",
     "skills/trellis-start/no-task-routing",
     "skills/trellis-brainstorm/planning-authorization",
-    "skills/trellis-brainstorm/auto-task-create"
+    "skills/trellis-brainstorm/auto-task-create",
+    "skills/trellis-brainstorm/planning-handoff",
+    "scripts/task-start-brief-gate"
   ]
 }

package/enhancements/0.6/overrides/conflicts.json

@@ -104,6 +104,81 @@
       "owner": "workflow-phase-ownership",
       "reason": "Phase 3.3/3.4 的受管 section 必须保留到权威 Skill 的一跳入口。"
     },
+    {
+      "id": "workflow-required-task-brief-review",
+      "severity": "error",
+      "target": ".trellis/workflow.md",
+      "whenOperations": [
+        "workflow-phase-1-activate"
+      ],
+      "assertion": {
+        "type": "required-literal",
+        "values": [
+          "<!-- BEGIN skill-garden patch workflow-phase-1-activate v0.6 -->\n#### 1.4 Activate task `[required · once]`\n\nBefore changing task status, load `trellis-task-brief`",
+          "display the full brief in chat, then stop the current turn and wait for planning review confirmation"
+        ]
+      },
+      "owner": "trellis-task-brief",
+      "reason": "Phase 1.4 必须自包含 brief 展示、停止和后续确认门禁。"
+    },
+    {
+      "id": "brainstorm-required-planning-handoff",
+      "severity": "error",
+      "target": ".agents/skills/trellis-brainstorm/SKILL.md",
+      "whenOperations": [
+        "brainstorm-planning-handoff",
+        "brainstorm-planning-readiness"
+      ],
+      "assertion": {
+        "type": "required-literal",
+        "values": [
+          "<!-- BEGIN skill-garden patch brainstorm-planning-handoff v0.6 -->\n## Planning Handoff",
+          "<!-- BEGIN skill-garden patch brainstorm-planning-readiness v0.6 -->\n- Planning artifacts are ready for the final brief handoff.",
+          "Implementation intent expressed before the final artifacts and full brief are shown authorizes planning only"
+        ]
+      },
+      "owner": "trellis-brainstorm",
+      "reason": "Brainstorm 收尾必须交给 task brief review，不能复用早期实现意向。"
+    },
+    {
+      "id": "brainstorm-required-planning-handoff-claude",
+      "severity": "error",
+      "target": ".claude/skills/trellis-brainstorm/SKILL.md",
+      "whenOperations": [
+        "brainstorm-planning-handoff",
+        "brainstorm-planning-readiness"
+      ],
+      "assertion": {
+        "type": "required-literal",
+        "values": [
+          "<!-- BEGIN skill-garden patch brainstorm-planning-handoff v0.6 -->\n## Planning Handoff",
+          "<!-- BEGIN skill-garden patch brainstorm-planning-readiness v0.6 -->\n- Planning artifacts are ready for the final brief handoff.",
+          "Implementation intent expressed before the final artifacts and full brief are shown authorizes planning only"
+        ]
+      },
+      "owner": "trellis-brainstorm",
+      "reason": "Claude 的 Brainstorm 最终入口必须保留相同 planning handoff。"
+    },
+    {
+      "id": "task-start-required-brief-gate",
+      "severity": "error",
+      "target": ".trellis/scripts/task.py",
+      "whenOperations": [
+        "task-start-brief-validator",
+        "task-start-brief-guard"
+      ],
+      "assertion": {
+        "type": "required-literal",
+        "values": [
+          "# BEGIN skill-garden patch task-start-brief-validator v0.6",
+          "# BEGIN skill-garden patch task-start-brief-guard v0.6",
+          "Error: Planning task brief.md is missing.",
+          "Error: Planning task brief.md is stale; newer artifacts:"
+        ]
+      },
+      "owner": "task-start-brief-gate",
+      "reason": "planning → in_progress 前必须确定性阻断缺失或过期 brief。"
+    },
     {
       "id": "workflow-no-covering-language",
       "severity": "error",

package/enhancements/0.6/overrides/patches/scripts/task-start-brief-gate/guard-content.py

@@ -0,0 +1,2 @@
+    if not _validate_planning_brief(full_path, task_json_path):
+        return 1

package/enhancements/0.6/overrides/patches/scripts/task-start-brief-gate/guard-selector.py

@@ -0,0 +1 @@
+    task_json_path = full_path / FILE_TASK_JSON

package/enhancements/0.6/overrides/patches/scripts/task-start-brief-gate/helper-content.py

@@ -0,0 +1,59 @@
+def _validate_planning_brief(full_path, task_json_path) -> bool:
+    """Validate that a planning task has a fresh derived brief before start.
+
+    Args:
+        full_path: Absolute task directory path.
+        task_json_path: Absolute path to the task metadata file.
+
+    Returns:
+        True when start may continue, otherwise False.
+    """
+    try:
+        task_json_exists = task_json_path.is_file()
+    except OSError as error:
+        print(colored(f"Error: Unable to validate planning task status: {error}", Colors.RED))
+        print("Hint: Fix task metadata access before retrying task.py start.")
+        return False
+
+    if not task_json_exists:
+        return True
+
+    data = read_json(task_json_path)
+    if not data:
+        print(colored("Error: Unable to read task status for brief validation.", Colors.RED))
+        print("Hint: Fix task.json before retrying task.py start.")
+        return False
+    if data.get("status") != "planning":
+        return True
+
+    brief_path = full_path / "brief.md"
+    try:
+        if not brief_path.is_file():
+            print(colored("Error: Planning task brief.md is missing.", Colors.RED))
+            print("Hint: Run trellis-task-brief, display the full brief, and wait for user confirmation before retrying task.py start.")
+            return False
+        brief_mtime = brief_path.stat().st_mtime_ns
+        authoritative_paths = [
+            full_path / name
+            for name in ("prd.md", "design.md", "implement.md")
+            if (full_path / name).is_file()
+        ]
+        stale_sources = [
+            path.name
+            for path in authoritative_paths
+            if path.stat().st_mtime_ns > brief_mtime
+        ]
+    except OSError as error:
+        print(colored(f"Error: Unable to validate planning brief freshness: {error}", Colors.RED))
+        print("Hint: Fix task artifact access, then refresh and review brief.md before retrying task.py start.")
+        return False
+
+    if stale_sources:
+        print(colored(
+            f"Error: Planning task brief.md is stale; newer artifacts: {', '.join(stale_sources)}.",
+            Colors.RED,
+        ))
+        print("Hint: Run trellis-task-brief, display the refreshed brief, and wait for user confirmation before retrying task.py start.")
+        return False
+
+    return True

package/enhancements/0.6/overrides/patches/scripts/task-start-brief-gate/helper-selector.py

@@ -0,0 +1,3 @@
+# =============================================================================
+# Command: start / finish
+# =============================================================================

package/enhancements/0.6/overrides/patches/scripts/task-start-brief-gate/patch.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": 2,
+  "id": "task-start-brief-gate",
+  "purpose": "planning_review",
+  "operations": [
+    {
+      "id": "task-start-brief-validator",
+      "operation": "insert",
+      "position": "after",
+      "targets": [{ "kind": "file", "path": ".trellis/scripts/task.py", "missing": "error", "markerStyle": "hash" }],
+      "selector": { "type": "literal", "source": "helper-selector.py" },
+      "content": { "source": "helper-content.py" }
+    },
+    {
+      "id": "task-start-brief-guard",
+      "operation": "insert",
+      "position": "after",
+      "targets": [{ "kind": "file", "path": ".trellis/scripts/task.py", "missing": "error", "markerStyle": "hash" }],
+      "selector": { "type": "literal", "source": "guard-selector.py" },
+      "content": { "source": "guard-content.py" }
+    }
+  ]
+}

package/enhancements/0.6/overrides/patches/skills/trellis-brainstorm/planning-handoff/content.md

@@ -0,0 +1,5 @@
+## Planning Handoff
+
+Once the Quality Bar is satisfied, load `trellis-task-brief`, refresh `brief.md` from the final planning artifacts, display the full brief in chat, and end the current turn. Wait for the user's planning review confirmation before running `task.py start` or beginning implementation.
+
+Implementation intent expressed before the final artifacts and full brief are shown authorizes planning only; it cannot be reused as the final review confirmation.

package/enhancements/0.6/overrides/patches/skills/trellis-brainstorm/planning-handoff/patch.json

@@ -0,0 +1,57 @@
+{
+  "schemaVersion": 2,
+  "id": "brainstorm-planning-handoff",
+  "purpose": "planning_review",
+  "operations": [
+    {
+      "id": "brainstorm-planning-handoff",
+      "operation": "insert",
+      "position": "after",
+      "targets": [
+        { "kind": "skill", "path": ".agent/skills/trellis-brainstorm/SKILL.md", "missing": "skip" },
+        { "kind": "skill", "path": ".agents/skills/trellis-brainstorm/SKILL.md", "missing": "skip" },
+        { "kind": "skill", "path": ".claude/skills/trellis-brainstorm/SKILL.md", "missing": "skip" },
+        { "kind": "skill", "path": ".codebuddy/skills/trellis-brainstorm/SKILL.md", "missing": "skip" },
+        { "kind": "skill", "path": ".cursor/skills/trellis-brainstorm/SKILL.md", "missing": "skip" },
+        { "kind": "skill", "path": ".devin/skills/trellis-brainstorm/SKILL.md", "missing": "skip" },
+        { "kind": "skill", "path": ".factory/skills/trellis-brainstorm/SKILL.md", "missing": "skip" },
+        { "kind": "skill", "path": ".github/skills/trellis-brainstorm/SKILL.md", "missing": "skip" },
+        { "kind": "skill", "path": ".kilocode/skills/trellis-brainstorm/SKILL.md", "missing": "skip" },
+        { "kind": "skill", "path": ".kiro/skills/trellis-brainstorm/SKILL.md", "missing": "skip" },
+        { "kind": "skill", "path": ".opencode/skills/trellis-brainstorm/SKILL.md", "missing": "skip" },
+        { "kind": "skill", "path": ".pi/skills/trellis-brainstorm/SKILL.md", "missing": "skip" },
+        { "kind": "skill", "path": ".qoder/skills/trellis-brainstorm/SKILL.md", "missing": "skip" },
+        { "kind": "skill", "path": ".reasonix/skills/trellis-brainstorm/SKILL.md", "missing": "skip" },
+        { "kind": "skill", "path": ".trae/skills/trellis-brainstorm/SKILL.md", "missing": "skip" },
+        { "kind": "skill", "path": ".zcode/skills/trellis-brainstorm/SKILL.md", "missing": "skip" }
+      ],
+      "selector": { "type": "markdown-section", "heading": "## Quality Bar" },
+      "baselines": ["quality-bar-baseline.md"],
+      "content": { "source": "content.md" }
+    },
+    {
+      "id": "brainstorm-planning-readiness",
+      "operation": "replace",
+      "targets": [
+        { "kind": "skill", "path": ".agent/skills/trellis-brainstorm/SKILL.md", "missing": "skip" },
+        { "kind": "skill", "path": ".agents/skills/trellis-brainstorm/SKILL.md", "missing": "skip" },
+        { "kind": "skill", "path": ".claude/skills/trellis-brainstorm/SKILL.md", "missing": "skip" },
+        { "kind": "skill", "path": ".codebuddy/skills/trellis-brainstorm/SKILL.md", "missing": "skip" },
+        { "kind": "skill", "path": ".cursor/skills/trellis-brainstorm/SKILL.md", "missing": "skip" },
+        { "kind": "skill", "path": ".devin/skills/trellis-brainstorm/SKILL.md", "missing": "skip" },
+        { "kind": "skill", "path": ".factory/skills/trellis-brainstorm/SKILL.md", "missing": "skip" },
+        { "kind": "skill", "path": ".github/skills/trellis-brainstorm/SKILL.md", "missing": "skip" },
+        { "kind": "skill", "path": ".kilocode/skills/trellis-brainstorm/SKILL.md", "missing": "skip" },
+        { "kind": "skill", "path": ".kiro/skills/trellis-brainstorm/SKILL.md", "missing": "skip" },
+        { "kind": "skill", "path": ".opencode/skills/trellis-brainstorm/SKILL.md", "missing": "skip" },
+        { "kind": "skill", "path": ".pi/skills/trellis-brainstorm/SKILL.md", "missing": "skip" },
+        { "kind": "skill", "path": ".qoder/skills/trellis-brainstorm/SKILL.md", "missing": "skip" },
+        { "kind": "skill", "path": ".reasonix/skills/trellis-brainstorm/SKILL.md", "missing": "skip" },
+        { "kind": "skill", "path": ".trae/skills/trellis-brainstorm/SKILL.md", "missing": "skip" },
+        { "kind": "skill", "path": ".zcode/skills/trellis-brainstorm/SKILL.md", "missing": "skip" }
+      ],
+      "selector": { "type": "literal", "source": "readiness-selector.md" },
+      "content": { "source": "readiness-content.md" }
+    }
+  ]
+}

package/enhancements/0.6/overrides/patches/skills/trellis-brainstorm/planning-handoff/quality-bar-baseline.md

@@ -0,0 +1,13 @@
+## Quality Bar
+
+Before declaring planning ready:
+
+- `prd.md` contains testable acceptance criteria.
+- `prd.md` has passed the PRD convergence pass: no unresolved temporary brainstorm sections, no duplicate facts across sections, and no lost anchors, decisions, or acceptance mappings.
+- Repository-answerable questions have already been answered through inspection.
+- Remaining open questions are genuinely about user intent or scope.
+- Complex tasks have `design.md` and `implement.md`.
+- Sub-agent-dispatch tasks have real curated entries in both `implement.jsonl` and `check.jsonl`; seed-only manifests are not ready.
+- The user has reviewed the final planning artifacts or explicitly approved proceeding.
+
+Do not start implementation until the user approves or asks for implementation.

package/enhancements/0.6/overrides/patches/skills/trellis-brainstorm/planning-handoff/readiness-content.md

@@ -0,0 +1,3 @@
+- Planning artifacts are ready for the final brief handoff.
+
+Planning readiness does not authorize `task.py start` or implementation.

package/enhancements/0.6/overrides/patches/skills/trellis-brainstorm/planning-handoff/readiness-selector.md

@@ -0,0 +1,3 @@
+- The user has reviewed the final planning artifacts or explicitly approved proceeding.
+
+Do not start implementation until the user approves or asks for implementation.

package/enhancements/0.6/overrides/patches/workflow/hub/content.md

@@ -50,6 +50,14 @@ structured blocker. Never force-delete or silently leave a dormant planning task
 
 Before `task.py start`, unclear scope, unresolved decisions, or non-testable acceptance criteria must return to `trellis-brainstorm`.
 
+#### Task Brief Handoff
+
+Before Phase 1.4, use `trellis-task-brief` to refresh `<task>/brief.md`, display it in full, and wait for user confirmation before `task.py start`.
+
+Implementation intent before that handoff authorizes planning only, not review confirmation.
+
+`brief.md` is derived; `prd.md` / `design.md` / `implement.md` remain authoritative.
+
 #### Project Knowledge Discovery
 
 Before choosing an approach for non-trivial project work, run project knowledge
@@ -72,19 +80,14 @@ If nothing matches, continue normally. Skip pure Q&A, simple read-only inspectio
 opening local tools, or trivial edits unless project conventions or local SOPs may
 change the approach.
 
-#### Task Brief Handoff
-
-Before Phase 1.4 `task.py start`, use `trellis-task-brief` to refresh `<task>/brief.md` from latest task artifacts, display it in chat, and wait for user confirmation.
-
-`brief.md` is derived; `prd.md` / `design.md` / `implement.md` remain authoritative.
-
-Before the first implement route, restate existing `<task>/brief.md` in chat. If missing, read task artifacts and suggest backfilling brief; do not invent one from memory.
-
 #### Flower Update Confirmation
 
 If `<flower-update>` has `priority: blocking_confirmation_required`, handle it first: briefly show `release_notes` when present, show `recommended_command`, and ask before running it.
 
-If `<flower-update-result>` requests `run_trellis_push_confirmation`, enter `trellis-push` planning with update changes as default candidates; still require file-list and commit-message confirmation.
+If `<flower-update-result>` requests `run_trellis_push_confirmation`, load and follow
+`trellis-push` before any Git inspection or plan; never replace it with a hand-written
+Git summary. Use update changes as default candidates and wait for file-list and
+commit-message confirmation.
 
 #### Active Task Scope Guard
 

package/enhancements/0.6/overrides/patches/workflow/task-brief-review/patch.json

@@ -0,0 +1,13 @@
+{
+  "schemaVersion": 2,
+  "id": "workflow-task-brief-review",
+  "purpose": "planning_review",
+  "operations": [{
+    "id": "workflow-phase-1-activate",
+    "operation": "replace",
+    "targets": [{ "kind": "workflow", "path": ".trellis/workflow.md", "missing": "error" }],
+    "selector": { "type": "markdown-section", "heading": "#### 1.4 Activate task `[required · once]`" },
+    "baselines": ["phase-1-activate-baseline.md"],
+    "content": { "source": "phase-1-activate-content.md" }
+  }]
+}

package/enhancements/0.6/overrides/patches/workflow/task-brief-review/phase-1-activate-baseline.md

@@ -0,0 +1,13 @@
+#### 1.4 Activate task `[required · once]`
+
+After artifact review, flip the task status to `in_progress`:
+
+```bash
+python3 ./.trellis/scripts/task.py start <task-dir>
+```
+
+For lightweight tasks, `prd.md` can be enough. For complex tasks, `prd.md`, `design.md`, and `implement.md` must exist and be reviewed before start. On sub-agent-dispatch platforms, `implement.jsonl` and `check.jsonl` must both have real curated entries before start. Runtime consumers tolerate missing or seed-only manifests for compatibility, but that tolerance is not a planning-ready state.
+
+After this command succeeds, the breadcrumb auto-switches to `[workflow-state:in_progress]`, and the rest of Phase 2 / 3 follows.
+
+If `task.py start` errors with a session-identity message (no context key from hook input, `TRELLIS_CONTEXT_ID`, or platform-native session env), follow the hint in the error to set up session identity, then retry.

package/enhancements/0.6/overrides/patches/workflow/task-brief-review/phase-1-activate-content.md

@@ -0,0 +1,13 @@
+#### 1.4 Activate task `[required · once]`
+
+Before changing task status, load `trellis-task-brief`, refresh `<task>/brief.md`, display the full brief in chat, then stop the current turn and wait for planning review confirmation. Earlier implementation intent is not confirmation.
+
+Lightweight tasks need `prd.md`; complex tasks also need `design.md` and `implement.md`. Sub-agent routes require real entries in both JSONL manifests.
+
+Only after the user confirms the displayed brief in a later message, run:
+
+```bash
+python3 ./.trellis/scripts/task.py start <task-dir>
+```
+
+If start rejects a missing or stale brief, repeat the brief handoff. Follow any session-identity hint; after success, enter `trellis-route(target=implement)`.

package/enhancements/MANIFEST.json

@@ -1,7 +1,7 @@
 {
-  "syncedAt": "2026-07-22T02:46:12.275Z",
+  "syncedAt": "2026-07-22T08:28:47.363Z",
   "syncedFrom": "vendor/skill-garden",
-  "sourceCommit": "39aa348603bed63ecb4eff5fbf938cf558167d24",
+  "sourceCommit": "6396573a9fb6776b326286390d41040ecdf4adcf",
   "common": {
     "codexSkills": [
       "craft-rpa",
@@ -147,12 +147,22 @@
         "hooks/inject-workflow-state/shared-runtime/content.py",
         "hooks/inject-workflow-state/shared-runtime/patch.json",
         "hooks/inject-workflow-state/shared-runtime/selector.py",
+        "scripts/task-start-brief-gate/guard-content.py",
+        "scripts/task-start-brief-gate/guard-selector.py",
+        "scripts/task-start-brief-gate/helper-content.py",
+        "scripts/task-start-brief-gate/helper-selector.py",
+        "scripts/task-start-brief-gate/patch.json",
         "skills/trellis-brainstorm/auto-task-create/content.md",
         "skills/trellis-brainstorm/auto-task-create/patch.json",
         "skills/trellis-brainstorm/auto-task-create/selector.md",
         "skills/trellis-brainstorm/planning-authorization/content.md",
         "skills/trellis-brainstorm/planning-authorization/patch.json",
         "skills/trellis-brainstorm/planning-authorization/selector.md",
+        "skills/trellis-brainstorm/planning-handoff/content.md",
+        "skills/trellis-brainstorm/planning-handoff/patch.json",
+        "skills/trellis-brainstorm/planning-handoff/quality-bar-baseline.md",
+        "skills/trellis-brainstorm/planning-handoff/readiness-content.md",
+        "skills/trellis-brainstorm/planning-handoff/readiness-selector.md",
         "skills/trellis-finish-work/exact-bookkeeping/baseline-agent.md",
         "skills/trellis-finish-work/exact-bookkeeping/baseline-command.md",
         "skills/trellis-finish-work/exact-bookkeeping/content.md",
@@ -221,7 +231,10 @@
         "workflow/states-planning/patch.json",
         "workflow/states-planning/planning-baseline.md",
         "workflow/states-planning/planning-inline-baseline.md",
-        "workflow/states-planning/subagent-content.md"
+        "workflow/states-planning/subagent-content.md",
+        "workflow/task-brief-review/patch.json",
+        "workflow/task-brief-review/phase-1-activate-baseline.md",
+        "workflow/task-brief-review/phase-1-activate-content.md"
       ],
       "bundles": [
         "finish-work.json",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flower-trellis",
-  "version": "0.5.0-beta.5",
+  "version": "0.5.0-beta.6",
   "description": "一键安装/升级 Trellis 并自动融合 skill-garden 强化包(默认 Claude + agents)",
   "type": "module",
   "bin": {
@@ -61,9 +61,9 @@
     "commit-and-tag-version": "^12.7.3"
   },
   "flowerReleaseNotes": {
-    "version": "0.5.0-beta.5",
+    "version": "0.5.0-beta.6",
     "source": "CHANGELOG.md",
-    "body": "### 🐛 修复 Bug Fixes\n\n* **enhancements:** 修复复杂 BUG 意图路由 ([e7877a3](https://github.com/SilentFlower/flower-trellis/commit/e7877a383efc7b840faad6175d2f15a2b7882a81))",
+    "body": "### 🐛 修复 Bug Fixes\n\n* **update:** 防止升级后绕过 trellis-push ([8a34b91](https://github.com/SilentFlower/flower-trellis/commit/8a34b91aa381c73ee56b9ba5bed960778ba2bbd3))\n* **workflow:** 强制任务 brief 确认门禁 ([7750c62](https://github.com/SilentFlower/flower-trellis/commit/7750c62417cabdf519e249deae147e1ec0ec14ac))",
     "truncated": false
   }
 }

package/src/commands/self-update.js

@@ -200,6 +200,6 @@ export async function selfUpdate(ctx) {
     post_action: "run_trellis_push_confirmation",
     release_notes: check.releaseNotes || null,
     ai_instruction:
-      "汇总本次升级产生的文件变动,进入 trellis-push 执行计划,展示具体文件列表和 commit message 后等待用户确认。",
+      "必须先加载并遵循 `trellis-push`,不得用自行 Git 检查或手写计划替代;以本次升级变动为默认候选,展示文件列表和 commit message 后等待确认。",
   });
 }