@pennixrv/trellis 0.6.45 → 0.7.0-beta.10

package/dist/templates/common/bundled-skills/trellis-meta/references/platform-files/overview.md

@@ -5,7 +5,7 @@ Trellis connects the same local architecture to different AI tools. `.trellis/`
 When a local AI modifies Trellis, it should distinguish two file categories first:
 
 - **Shared files**: `.trellis/workflow.md`, `.trellis/tasks/`, `.trellis/spec/`, `.trellis/scripts/`.
-- **Platform files**: `.claude/`, `.snow/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.trae/`, `.kilocode/`, `.agent/`, `.devin/`, `.reasonix/`, `.zcode/`, `.kimi-code/`, and similar directories.
+- **Platform files**: `.claude/`, `.snow/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.trae/`, `.kilocode/`, `.agent/`, `.devin/`, `.reasonix/`, `.zcode/`, `.kimi-code/`, `.dsh/`, and similar directories.
 
 Platform files do not store business state. They let the corresponding AI tool read Trellis state, call Trellis scripts, and load Trellis skills/agents/hooks.
 

package/dist/templates/common/bundled-skills/trellis-meta/references/platform-files/platform-map.md

@@ -19,14 +19,14 @@ This page lists common Trellis file locations in a user project by platform. Whe
 | CodeBuddy | `--codebuddy` | `.codebuddy/` | `.codebuddy/skills/` | `.codebuddy/agents/` | `.codebuddy/hooks/` + `.codebuddy/settings.json` |
 | GitHub Copilot | `--copilot` | `.github/` | `.github/skills/` | `.github/agents/` | `.github/copilot/hooks/` + prompts |
 | Factory Droid | `--droid` | `.factory/` | `.factory/skills/` | `.factory/droids/` | `.factory/hooks/` + settings |
-| DeepSeek Harness (dsh) | `--dsh` | `.dsh/` | `.agents/skills/` (shared) + `.dsh/skills/` (entry skills) | None (workflow skills run implement/check inline) | None (class-2 pull-based; no project hooks/settings) |
 | Pi Agent | `--pi` | `.pi/` | `.agents/skills/` | `.pi/agents/` | `.pi/extensions/trellis/` (native `trellis_subagent` tool) + `.pi/settings.json` |
 | Trae IDE | `--trae` | `.trae/` | `.trae/skills/` | `.trae/agents/` | `.trae/hooks/` + `.trae/hooks.json` |
 | Reasonix | `--reasonix` | `.reasonix/` | `.reasonix/skills/` | None — sub-agents are skills with `runAs: subagent` frontmatter | None |
 | ZCode | `--zcode` | `.zcode/` | `.zcode/skills/` | `.zcode/agents/` | `.zcode/hooks/` + `.zcode/config.json` (SessionStart + UserPromptSubmit + PreToolUse Agent/Task); sub-agents use hook-injected context |
 | Grok Build | `--grok` | `.grok/` | `.grok/skills/` | `.grok/agents/` | pull-based prelude (no hooks; flat `.grok/commands/trellis-*.md`) |
-| Kimi Code | `--kimi` | `.kimi-code/` | `.agents/skills/` (shared) + `.kimi-code/skills/` | `.kimi-code/agents/` (custom sub-agents; same prompts also ship as skills) | None (pull-based prelude; no project hooks/settings) |
+| Kimi Code | `--kimi` | `.kimi-code/` | `.agents/skills/` (shared) + `.kimi-code/skills/` | None — agent prompts are skills under `.kimi-code/skills/` and dispatch to the built-in `coder` | None (pull-based prelude; no project hooks/settings) |
 | Snow CLI | `--snow` | `.snow/` | `.snow/skills/` | `.snow/agents/` (auto-discovered; primary path) | class-1: auto inject + project agents + `beforeSubAgentStart` (`.snow/hooks/` `session`/`user`/`subagent` modes -> `additionalContext` JSON); no legacy sub-agent JSON; commands `.snow/commands/trellis-*.json` |
+| DeepSeek Harness | `--dsh` | `.dsh/` | `.agents/skills/` (shared) + `.dsh/skills/` | None — role prompts are collision-free `trellis-agent-*` skills under `.dsh/skills/` | None installed by Trellis (pull-based roles; optional `dsh-trellis` adds event-driven wait, otherwise foreground dispatch) |
 
 ## Capability Groups
 
@@ -49,8 +49,9 @@ These platforms usually have `trellis-research`, `trellis-implement`, and `trell
 - Reasonix (delivered as skills with `runAs: subagent` under `.reasonix/skills/`, not as a separate `agents/` directory)
 - ZCode
 - Grok Build (`.grok/agents/`; dispatch via `spawn_subagent` with `subagent_type`)
-- Kimi Code (`.kimi-code/agents/`; the same prompts are also delivered as skills under `.kimi-code/skills/`)
+- Kimi Code (delivered as skills under `.kimi-code/skills/`; dispatched to the built-in `coder`, including research because it must persist files)
 - Snow CLI (`.snow/agents/`; auto-discovered project agents + class-1 hooks)
+- DeepSeek Harness (role prompts delivered as `.dsh/skills/trellis-agent-*/SKILL.md`; dispatched through the continuable `subagent` tool)
 
 When changing implementation/check/research behavior, look for the corresponding platform agent files first.
 
@@ -74,7 +75,7 @@ When changing behavior, inspect workflows and skills first. Do not assume Trelli
 
 ### Shared `.agents/skills/`
 
-Codex, Gemini CLI, Pi Agent, Kimi Code, and DeepSeek Harness (dsh) write the shared `.agents/skills/` layer. Some tools that support agentskills.io can also read this directory. If the user wants multiple compatible tools to share one skill, consider `.agents/skills/` first, but do not assume every platform reads it. ZCode keeps Trellis-managed skills under `.zcode/skills/`.
+Codex, Gemini CLI, Pi Agent, Kimi Code, and DeepSeek Harness write the shared `.agents/skills/` layer. Some tools that support agentskills.io can also read this directory. If the user wants multiple compatible tools to share one skill, consider `.agents/skills/` first, but do not assume every platform reads it. ZCode keeps Trellis-managed skills under `.zcode/skills/`.
 
 ## Decision Rules When Modifying Platform Files
 

package/dist/templates/common/bundled-skills/trellis-meta/references/platform-files/skills-and-commands.md

@@ -34,6 +34,7 @@ Trellis workflow skills usually share one semantic set: brainstorm, before-dev,
 | Reasonix | `.reasonix/skills/` |
 | ZCode | `.zcode/skills/`, `.zcode/commands/` |
 | Kimi Code | `.agents/skills/`, `.kimi-code/skills/` (commands delivered as `/skill:trellis-*` skills) |
+| DeepSeek Harness | `.agents/skills/`, `.dsh/skills/` (entry skills load by bare `trellis-*` names; role prompts use `trellis-agent-*`) |
 
 In a user project, use the files actually generated by init as authoritative.
 

package/dist/templates/common/bundled-skills/trellis-session-insight/SKILL.md

@@ -11,7 +11,7 @@ It is intentionally a **capability skill, not a workflow**. There is no fixed ou
 
 ## What `trellis mem` is
 
-A local CLI that indexes the user's past Claude Code, Codex, Pi Agent, and ZCode conversation logs and lets you list, search, slice by Trellis task boundaries, and dump cleaned dialogue from them. Claude and Codex use `~/.claude/projects/` and `~/.codex/sessions/`. Pi uses its default or environment-configured session root, global `~/.pi/agent/settings.json`, and the scoped project's `.pi/settings.json`; relative `sessionDir` values resolve from the settings file directory. Project-local Pi settings require project-scoped lookup through the current cwd or `--cwd`. ZCode uses `~/.zcode/cli/db/db.sqlite`. OpenCode logs are not yet indexable (provider adapter pending) — when an OpenCode session is the obvious target, surface that limitation rather than guessing.
+A local CLI that indexes the user's past Claude Code, Codex, Devin CLI, Grok, OpenCode, Pi Agent, and ZCode conversation logs and lets you list, search, slice by Trellis task boundaries, and dump cleaned dialogue from them. Claude and Codex use `~/.claude/projects/` and `~/.codex/sessions/`. Devin CLI (Cognition terminal agent, not `trellis init --devin` Desktop) uses `~/.local/share/devin/cli/sessions.db`. Grok uses `~/.grok/sessions/`. OpenCode uses `~/.local/share/opencode/opencode.db` (zero-dependency SQLite reader). Pi uses its default or environment-configured session root, global `~/.pi/agent/settings.json`, and the scoped project's `.pi/settings.json`; relative `sessionDir` values resolve from the settings file directory. Project-local Pi settings require project-scoped lookup through the current cwd or `--cwd`. ZCode uses `~/.zcode/cli/db/db.sqlite`.
 
 Nothing in `mem` is uploaded. All reads are local.
 
@@ -68,7 +68,7 @@ trellis mem list --cwd <project-path>
 trellis mem projects   # → list active project cwds, then narrow
 ```
 
-Phase slicing (`--phase brainstorm|implement|all`) cuts the session at `task.py create` and `task.py start` boundaries. For a finish-work review of the current task, `--phase brainstorm` recovers the planning discussion and `--phase implement` recovers the execution loop. Default is `all`.
+Phase slicing (`--phase brainstorm|implement|all`) cuts the session at `task.py create`/`replan` and `task.py start` boundaries. For a finish-work review of the current task, `--phase brainstorm` recovers the planning discussion and `--phase implement` recovers the execution loop. Default is `all`.
 
 ## Triggering patterns
 

package/dist/templates/common/bundled-skills/trellis-session-insight/references/cli-quick-reference.md

@@ -16,14 +16,14 @@ Full flag reference for the five subcommands. Pin this as the authoritative sour
 
 | Flag                                          | Subcommands       | Meaning                                                                                                                                                    |
 | --------------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--platform claude\|codex\|opencode\|pi\|all` | all               | Default `all`. OpenCode adapter is currently a stub on `0.6.0-beta.*` — see "Caveats" below.                                                               |
+| `--platform claude\|codex\|devin\|grok\|opencode\|pi\|zcode\|all` | all               | Default `all`. `devin` is Cognition Devin CLI (`sessions.db`), not `trellis init --devin` (Desktop). |
 | `--since YYYY-MM-DD`                          | list / search     | Inclusive lower date bound.                                                                                                                                |
 | `--until YYYY-MM-DD`                          | list / search     | Inclusive upper date bound.                                                                                                                                |
 | `--global`                                    | list / search     | Include sessions from every project on this machine. Default is the current project `cwd`.                                                                 |
 | `--cwd <path>`                                | list / search     | Force a specific project cwd instead of inferring from where you are.                                                                                      |
 | `--limit N`                                   | list / search     | Cap output rows. Default `50`.                                                                                                                             |
 | `--grep KW`                                   | extract / context | Filter turns by keyword. Multi-token AND when whitespace-separated.                                                                                        |
-| `--phase brainstorm\|implement\|all`          | extract           | Slice session by Trellis task boundaries. `brainstorm` = `[task.py create, task.py start)`. `implement` = turns outside brainstorm windows. Default `all`. |
+| `--phase brainstorm\|implement\|all`          | extract           | Slice session by Trellis task boundaries. `brainstorm` = `[task.py create/replan, task.py start)`. `implement` = turns outside brainstorm windows. Default `all`. |
 | `--turns N`                                   | context           | Number of hit turns to return. Default `3`.                                                                                                                |
 | `--around N`                                  | context           | Surrounding turns to include per hit. Default `1`.                                                                                                         |
 | `--max-chars N`                               | context           | Total character budget. Default `6000` (~1500 tokens).                                                                                                     |
@@ -56,6 +56,7 @@ trellis mem projects
 ## Caveats
 
 - **OpenCode adapter is a stub on `0.6.0-beta.*`.** When `--platform` resolves to OpenCode (or `all` and OpenCode would be included), `mem` prints a one-line "reader unavailable" notice and continues with the other platforms. Don't promise OpenCode coverage in your reply until the adapter ships.
+- **`--platform devin` is Cognition Devin CLI** (`~/.local/share/devin/cli/sessions.db`). It is not `trellis init --devin` (Devin Desktop / Cascade) and not Factory Droid.
 - **`--phase` slicing depends on `task.py create` / `task.py start` invocations appearing in the recorded bash calls of the session.** Sessions where the user ran `task.py` from a different terminal — outside the recorded AI loop — will not have phase boundaries. `--phase all` is the safe fallback.
 - **`mem` indexes platform JSONL files directly.** If the user has cleared their Claude / Codex / Pi session storage, `mem` cannot recover what is no longer on disk.
 - **`mem` is read-only.** No remote sync, no edits to platform JSONL. Any write you do based on `mem` findings is your own follow-up call into the editing tools available to you.

package/dist/templates/common/commands/continue.md

@@ -24,11 +24,13 @@ Shows the Phase Index (Plan / Execute / Finish) with routing + skill mapping.
 
 `get_context.py` shows the active task's `status` field. Route by `status` + artifact presence. This command replaces the user needing to remember the Trellis flow; it does not itself approve implementation.
 
-- `status=planning` + `task.json.meta.delivery_mode = "analysis_only"` → complete the PRD's bounded evidence work, verify its acceptance criteria and no-change boundary, then commit task artifacts and archive directly. Do not run `task.py start`; a protected-target change requires a separate change-bearing task.
+- `status=planning` + `task.json.meta.delivery_mode = "analysis_only"` → first confirm the task still satisfies the bounded evidence-only eligibility rule; then complete the PRD's evidence work, verify its acceptance criteria and no-change boundary, and archive directly. Do not run `task.py start`; a protected-target change requires a separate change-bearing task.
 - `status=planning` + no `prd.md` → **1.1** (load `trellis-brainstorm`)
+- `status=planning` + a recorded `decision-needed` or unsealed decision chain → return to the planning frontier and load `pennix-decision-gates` when independent material questions can be batched.
+- `status=in_progress` + a material unresolved decision → record the reason and run `task.py replan <task> "<reason>"`; do not ask a native question during implementation.
 - `status=planning` + `prd.md` only → decide whether the task is lightweight or complex. Lightweight can move to **1.4** review; complex returns to **1.1** to add `design.md` + `implement.md`.
 - `status=planning` + complex artifacts complete + sub-agent jsonl not curated (empty, or only a legacy `_example` placeholder row) → **1.3**
-- `status=planning` + required artifacts complete + required jsonl curated or inline mode → **1.4** (ask for start review; only run `task.py start` after user confirms)
+- `status=planning` + required artifacts complete + required jsonl curated or inline mode → run the Planning Seal closure pass, then **1.4** (ask for start review; only run `task.py start` after user confirms)
 - `status=in_progress` + implementation not started → **2.1**
 - `status=in_progress` + implementation done, not yet checked → **2.2**
 - `status=in_progress` + check passed → **3.3** (spec update) → **3.4** (commit)

package/dist/templates/common/skills/brainstorm.md

@@ -6,12 +6,14 @@ A request to build, implement, fix, refactor, or "go ahead" is not approval to l
 
 For every non-trivial task, the user must respond at least once after the initial request before implementation begins. If no clarification is needed, that response must approve the final planning summary described below.
 
-While any user-owned product, scope, UX, compatibility, risk, or acceptance decision remains unresolved, end the turn with exactly one highest-value question. Do not edit product code, dispatch implementation, or run `task.py start`.
+While any user-owned product, scope, UX, compatibility, risk, or acceptance decision remains unresolved, keep the task in planning. First inventory evidence and decision dependencies. If at least two independent material decisions remain and `pennix-decision-gates` is available, delegate one bounded batch of up to three frontier questions; otherwise ask the single highest-value question. Do not edit product code, dispatch implementation, or run `task.py start` until the decision chain is sealed.
 
 ## Analysis-Only Exception
 
 When `task.json.meta.delivery_mode = "analysis_only"` exactly and the PRD names a bounded evidence deliverable plus a no-change boundary for product source, runtime configuration, deployment, credentials, and external systems, task-creation consent authorizes that evidence work. Do not require a second planning approval or run `task.py start`: perform the declared research, audit, or design work while status remains `planning`, record the evidence, verify acceptance criteria and the boundary, commit task artifacts, and archive directly. If the evidence recommends a protected-target change, record it and create a separate change-bearing task before doing it.
 
+This exception is eligible only for a bounded evidence deliverable with no material user decision, design or implementation plan, cross-owner coordination, security or deployment change, release or credential action, or protected downstream task. Calling work "research", deferring source edits, or working in an audit/root repository does not make it analysis-only. If any of those conditions apply, use the normal complex planning and implementation-approval path.
+
 All other tasks follow the planning and implementation approval gates below.
 
 ## Non-Negotiable Evidence Rule
@@ -24,6 +26,10 @@ Do not ask the user to confirm facts that the repository can answer. Ask only fo
 
 Repository evidence establishes current behavior and technical constraints. The user's intended behavior, feature scope boundaries, and UX preferences are never answerable by repository evidence alone, even when an existing pattern exists; existing patterns are options and recommendation evidence, not decisions.
 
+## Evidence Units For Read-Heavy Work
+
+When research, audit, review, or investigation is too large to leave one independently useful conclusion in the current bounded session, split it into evidence units. Each unit must have one question or scope, a minimal evidence range, a destination artifact, and a stop condition; write its facts, conclusion or blocker, unknowns, and recovery point before starting another unit. Size units so one normal context window can finish and persist one useful result; do not promise an exact token or time limit. Routine navigation and transient tool output do not need an artifact. Create a child task only when the unit has an independent owner, lifecycle, and acceptance contract.
+
 ---
 
 Use this skill during Phase 1 planning to turn the user's request into clear requirements and planning artifacts.
@@ -54,18 +60,18 @@ Use a concise title from the user's request. Both the title and `--description`
    - product intent still needed from the user
    - scope or risk decisions still needed from the user
    - likely out-of-scope items
-4. If a user-owned decision remains, ask the single highest-value question, include your recommendation and trade-off, then stop. Do not perform implementation work in the same turn.
-5. After each user answer, update `prd.md`, recompute the decision inventory, and repeat from step 2.
+4. If user-owned decisions remain, calculate the independent frontier. Use `pennix-decision-gates` for a bounded batch when two or more independent material decisions are ready; otherwise ask the single highest-value question. Include recommendation and trade-off. Yield only while the answer is unavailable.
+5. When the host returns the current continuation's answer, immediately persist it in `prd.md` or the decision artifact, recheck evidence and conflicts, recalculate the frontier, and continue the same planning loop. Do not create a second Trellis lifecycle for the same decision chain. Stop only for a new unresolved frontier, a real capability or authority block, or a final sealed summary awaiting implementation approval.
 6. When no user-owned decision remains, create or update `design.md` and `implement.md` for complex tasks.
-7. Run the requirement convergence gate, then the PRD convergence pass.
+7. Run the requirement convergence gate, then the PRD convergence pass. Finish with one Planning Seal closure pass.
 8. Present the final planning summary and stop. Do not run `task.py start` or edit product code in the same turn.
-9. Only a subsequent user message that explicitly approves the latest planning summary authorizes `task.py start` and implementation. If the artifacts change materially after approval, repeat the final review.
+9. Only a subsequent user message that explicitly approves the latest planning summary authorizes `task.py start` and implementation. If implementation reveals a material unresolved decision, record `decision-needed`, run `task.py replan <task> "<reason>"`, and return through this planning flow; do not open a popup during implementation.
 
 Do not invent a project-specific product/spec hierarchy. If the repository already has product, domain, or spec docs, use them. If it does not, proceed with the evidence that exists.
 
 ## Question Rules
 
-Ask only one question per message.
+Ask one bounded batch per message: include up to three independent material frontier questions. Ask exactly one question only when it is the sole remaining material decision or later decisions depend on its answer.
 
 Each question must include:
 
@@ -140,6 +146,8 @@ Lightweight tasks may omit `design.md` and `implement.md`; they may not skip evi
 
 The final planning summary must show Goal, In Scope, Out of Scope, Acceptance Criteria, Key Decisions, relevant Risks or Deferred Items, and artifact status.
 
+The Planning Seal closure pass must reconcile `task.json`, `prd.md`, `design.md`, `implement.md`, research, decision records, and manifests; verify the actual modification targets and branches, ordered dependencies and release steps, validation and rollback, dynamic-fact dispositions and replan triggers, and that every material decision has an owner and a fixed outcome. Remove static ambiguity before implementation: no `TBD`, `TODO`, `decision-needed`, unowned option, unspecified branch, open implementation path, validation gap, or conditional acceptance may remain. A material discovery invalidates the seal and returns to planning; implementation may consume only a sealed plan.
+
 ## Artifact Rules
 
 `prd.md` records requirements and acceptance:

package/dist/templates/copilot/hooks/session-start.py

@@ -452,6 +452,25 @@ def _strip_breadcrumb_tag_blocks(content: str) -> str:
     return re.sub(r"\n{3,}", "\n\n", stripped).strip()
 
 
+def _resolve_workflow_md(root: Path, input_data: dict) -> Path:
+    """Resolve the active task's workflow file, falling back to the global one.
+
+    The per-task resolution rule lives in common.workflow_selection inside
+    .trellis/scripts. Older installed projects may not ship that module, and
+    hooks must never crash the session — ANY failure (import error, old
+    scripts tree, resolver bug) falls back to the global workflow.md.
+    """
+    try:
+        scripts_dir = root / ".trellis" / "scripts"
+        if str(scripts_dir) not in sys.path:
+            sys.path.insert(0, str(scripts_dir))
+        from common.workflow_selection import resolve_workflow_md  # type: ignore[import-not-found]
+
+        return resolve_workflow_md(root, input_data, platform="copilot")
+    except Exception:
+        return root / ".trellis" / "workflow.md"
+
+
 def _build_workflow_toc(workflow_path: Path) -> str:
     """Inject only the compact Phase Index summary for SessionStart."""
     content = read_file(workflow_path)
@@ -503,7 +522,7 @@ Trellis compact SessionStart context. Use it to orient the session; load details
     output.write("\n</current-state>\n\n")
 
     output.write("<trellis-workflow>\n")
-    output.write(_build_workflow_toc(trellis_dir / "workflow.md"))
+    output.write(_build_workflow_toc(_resolve_workflow_md(project_dir, hook_input)))
     output.write("\n</trellis-workflow>\n\n")
 
     output.write("<guidelines>\n")

package/dist/templates/copilot/prompts/brainstorm.prompt.md

@@ -10,7 +10,11 @@ A request to build, implement, fix, refactor, or "go ahead" is not approval to l
 
 For every non-trivial task, the user must respond at least once after the initial request before implementation begins. If no clarification is needed, that response must approve the final planning summary described below.
 
-While any user-owned product, scope, UX, compatibility, risk, or acceptance decision remains unresolved, end the turn with exactly one highest-value question. Do not edit product code, dispatch implementation, or run `task.py start`.
+While any user-owned product, scope, UX, compatibility, risk, or acceptance decision remains unresolved, keep the task in planning. First inventory evidence and decision dependencies. If at least two independent material decisions remain and `pennix-decision-gates` is available, delegate one bounded batch of up to three frontier questions; otherwise ask the single highest-value question. Do not edit product code, dispatch implementation, or run `task.py start` until the decision chain is sealed.
+
+## Analysis-Only Exception
+
+When `task.json.meta.delivery_mode = "analysis_only"` exactly and the PRD names a bounded evidence deliverable plus a no-change boundary for product source, runtime configuration, deployment, credentials, and external systems, task-creation consent authorizes that evidence work. Keep status `planning`, record and verify the evidence, commit task artifacts, and archive directly; do not run `task.py start` or wait for a second implementation approval. This exception is eligible only when there is no material user decision, design or implementation plan, cross-owner coordination, security or deployment change, release or credential action, or protected downstream task. Otherwise use normal complex planning.
 
 ## Non-Negotiable Evidence Rule
 
@@ -22,6 +26,10 @@ Do not ask the user to confirm facts that the repository can answer. Ask only fo
 
 Repository evidence establishes current behavior and technical constraints. The user's intended behavior, feature scope boundaries, and UX preferences are never answerable by repository evidence alone, even when an existing pattern exists; existing patterns are options and recommendation evidence, not decisions.
 
+## Evidence Units For Read-Heavy Work
+
+When research, audit, review, or investigation is too large for one independently useful conclusion in the current session, split it into evidence units. Each unit has one question or scope, a minimal evidence range, a destination artifact, and a stop condition; persist facts, conclusion or blocker, unknowns, and a recovery point before starting another unit. Size each unit for one normal context window without promising an exact token or time limit.
+
 ---
 
 Use this skill during Phase 1 planning to turn the user's request into clear requirements and planning artifacts.
@@ -52,18 +60,18 @@ Use a concise title from the user's request. Both the title and `--description`
    - product intent still needed from the user
    - scope or risk decisions still needed from the user
    - likely out-of-scope items
-4. If a user-owned decision remains, ask the single highest-value question, include your recommendation and trade-off, then stop. Do not perform implementation work in the same turn.
-5. After each user answer, update `prd.md`, recompute the decision inventory, and repeat from step 2.
+4. If user-owned decisions remain, calculate the independent frontier. Use `pennix-decision-gates` for a bounded batch when two or more independent material decisions are ready; otherwise ask the single highest-value question. Include recommendation and trade-off. Yield only while the answer is unavailable.
+5. When the host returns the current continuation's answer, persist it in `prd.md` or the decision artifact, recheck evidence and conflicts, recalculate the frontier, and continue the same planning loop. Stop only for a new unresolved frontier, a real capability or authority block, or a final sealed summary awaiting implementation approval.
 6. When no user-owned decision remains, create or update `design.md` and `implement.md` for complex tasks.
-7. Run the requirement convergence gate, then the PRD convergence pass.
+7. Run the requirement convergence gate, then the PRD convergence pass. Finish with one Planning Seal closure pass.
 8. Present the final planning summary and stop. Do not run `task.py start` or edit product code in the same turn.
-9. Only a subsequent user message that explicitly approves the latest planning summary authorizes `task.py start` and implementation. If the artifacts change materially after approval, repeat the final review.
+9. Only a subsequent user message that explicitly approves the latest planning summary authorizes `task.py start` and implementation. If implementation reveals a material unresolved decision, record `decision-needed`, run `task.py replan <task> "<reason>"`, and return through this planning flow; do not open a popup during implementation.
 
 Do not invent a project-specific product/spec hierarchy. If the repository already has product, domain, or spec docs, use them. If it does not, proceed with the evidence that exists.
 
 ## Question Rules
 
-Ask only one question per message.
+Ask one bounded batch per message: include up to three independent material frontier questions. Ask exactly one question only when it is the sole remaining material decision or later decisions depend on its answer.
 
 Each question must include:
 
@@ -95,6 +103,8 @@ Lightweight tasks may omit `design.md` and `implement.md`; they may not skip evi
 
 The final planning summary must show Goal, In Scope, Out of Scope, Acceptance Criteria, Key Decisions, relevant Risks or Deferred Items, and artifact status.
 
+The Planning Seal closure pass reconciles `task.json`, `prd.md`, `design.md`, `implement.md`, research, decision records, and manifests; verifies targets, branches, dependencies, release, validation, rollback, dynamic-fact dispositions, and replan triggers; and fixes every material decision to an owner and outcome. No `TBD`, `TODO`, `decision-needed`, unowned option, unspecified branch, open implementation path, validation gap, or conditional acceptance may remain. Any material discovery invalidates the seal and returns to planning.
+
 ## Artifact Rules
 
 `prd.md` records requirements and acceptance:

package/dist/templates/dsh/DSH.md

@@ -1,15 +1,17 @@
 # Trellis on DeepSeek Harness (dsh)
 
-dsh is a **class-2 pull-based** Trellis host: no session-start hook auto-injects
-workflow context, so the agent loads the Trellis skills on demand through its
-skill-loader tool.
+dsh is a **class-2 pull-based** Trellis host. It discovers Trellis skills from
+the project, uses native continuable sub-agents for isolated implementation and
+review roles, and exposes a stable `DSH_SESSION_ID` to every managed shell.
 
-| Capability | Status |
-| --- | --- |
-| Skills (`.agents/skills/trellis-*/SKILL.md`) | Works — dsh discovers this shared root natively |
-| Entry skills (`.dsh/skills/trellis-*/SKILL.md`) | Works — dsh's own project skill root (highest rank) |
-| Context hooks | None — pull-based: skills read `.trellis/` files directly |
-| Sub-agents | None shipped — implement/check/research run inline via the workflow skills |
+| Capability | Without companion plugin | With `dsh-trellis` |
+| --- | --- | --- |
+| Shared and entry skills | Works | Works |
+| Session-scoped active task | Works through verified `DSH_SHELL=1` + `DSH_SESSION_ID`, including nested launches | Managed per-execution identity can forward a distinct child session |
+| Implement/check/research roles | Foreground native sub-agent | Background native sub-agent |
+| Per-turn workflow breadcrumb | Not available | Injected from `workflow.md` |
+| Event-driven child wait | Not available | `trellis_wait` |
+| Utility commands | Not available | `/trellis-status`, `/trellis-finish` |
 
 ## Quick start
 
@@ -20,37 +22,59 @@ dsh web        # or: dsh --profile headless "start a Trellis task for ..."
 
 In dsh:
 
-1. Open a session in the project root and describe the work in natural
-   language. For a new task the agent should load the `trellis-start` skill,
-   which reads the current task state from `.trellis/` and routes to
-   `trellis-brainstorm` (unclear requirements), `trellis-before-dev` (about to
-   write code), `trellis-check` (done coding), or `trellis-update-spec`
-   (learned something worth capturing).
-2. Entry skills are `trellis-start` / `trellis-continue` / `trellis-finish-work`
-   in `.dsh/skills/`. You can also ask for them by name at any time.
-3. Type `/trellis:finish-work` is a slash-command convention from other hosts —
-   dsh has no slash palette, so say "finish the trellis task" instead, and the
-   agent loads `trellis-finish-work`.
+1. Describe the work in natural language and load `trellis-start` when a
+   session needs explicit Trellis bootstrap.
+2. The main session dispatches `trellis-agent-research`,
+   `trellis-agent-implement`, and `trellis-agent-check` through DSH's native
+   `subagent` tool. Each child loads exactly one matching role skill.
+3. Finish through `trellis-finish-work`, which preserves the required order:
+   commit, archive, then journal.
+
+## Companion plugin fallback contract
+
+The Trellis adapter does not install a DSH profile plugin. Before dispatching a
+role, check whether the `trellis_wait` tool is available:
+
+- If available, use DSH's default continuable background mode, continue
+  independent work, then call `trellis_wait` once per dependent child id and
+  consume each native settlement notice before entering the dependent gate.
+- If unavailable, dispatch every child with `run_in_background: false` from the outset
+  so the dependent workflow gate cannot overtake it.
+
+Never replace either path with shell sleep, polling loops, `job_output`, or
+repeated agent-list polling.
+
+## Nested host sessions
+
+DSH inherits ordinary environment variables from the process that launches it.
+If that outer process is already an active Trellis session,
+`TRELLIS_CONTEXT_ID` would otherwise override the inner `DSH_SESSION_ID`.
+DSH rebuilds its complete `DSH_*` namespace for each managed shell, so the beta
+adapter treats `DSH_SHELL=1` together with `DSH_SESSION_ID` as the current DSH
+identity and resolves it before an inherited generic override, even without the
+plugin. The optional plugin additionally contributes a trusted
+`DSH_TRELLIS_CONTEXT_ID` when it must forward a child identity that differs
+from the shell's own session id.
 
 ## File map
 
-- `.agents/skills/` — auto-triggered workflow skills (`trellis-before-dev`,
-  `trellis-brainstorm`, `trellis-check`, `trellis-break-loop`,
-  `trellis-update-spec`) plus the bundled `trellis-meta` /
-  `trellis-spec-bootstrap` / `trellis-session-insight` skills. Byte-identical
-  to Codex / Gemini CLI / Pi / Kimi writes into the same shared root.
-- `.dsh/skills/` — dsh-private entry skills (`trellis-start` /
-  `trellis-continue` / `trellis-finish-work`).
-- `.trellis/` — specs, tasks, workspace memory, and the shared scripts the
-  skills invoke (`get_context.py`, `task.py`, ...).
+- `.agents/skills/` — shared workflow and bundled skills, byte-identical to
+  the other Agent Skills writers.
+- `.dsh/skills/trellis-{start,continue,finish-work}/` — DSH-private entry
+  skills.
+- `.dsh/skills/trellis-agent-{research,implement,check}/` — child-only role
+  skills; implement/check include the pull-based task context prelude.
+- `.dsh/DSH.md` — this operator guide.
+- `.trellis/` — workflow, specs, tasks, workspace journal, and shared scripts.
 
 ## Notes
 
-- Skill scripts pass `--platform dsh` to `get_context.py`; the value is used
-  as a platform-scoped context key.
-- The shipped `minimal` agent preset composes only `bash` +
-  `str_replace_editor`; the default presets include `web_search` and the
-  filesystem/terminal tools the skills assume.
-- dsh has no project-level sub-agent definition surface, so Trellis ships no
-  `trellis-implement` / `trellis-check` / `trellis-research` agent prompts
-  here — the workflow skills run those phases inline in the main session.
+- Generated Python commands use `python3` in source templates and are rendered
+  to the detected Windows launcher during `trellis init` / `trellis update`.
+- Role dispatch prompts start with `Active task: <task path>`. This exact task
+  path is the child's primary context source; children must not guess globally.
+- Each `dsh --profile headless` invocation creates a fresh DSH session. Do not
+  expect an active-task pointer to persist across separate headless calls; keep
+  the workflow in one session or explicitly resume its returned session id.
+- The optional companion plugin is maintained separately at
+  <https://github.com/SajoLuo/dsh-trellis>.

package/dist/templates/dsh/agents/trellis-check.md

@@ -0,0 +1,99 @@
+---
+name: trellis-check
+user-invocable: false
+description: |
+  Child-agent-only quality role for Trellis. Main sessions must not load this
+  skill directly. Reviews code changes against specs and self-fixes issues.
+---
+# Check Agent
+
+You are the Check Agent in the Trellis workflow.
+
+## Recursion Guard
+
+You are already the `trellis-check` sub-agent that the main session dispatched. Do the review and fixes directly.
+
+- Do NOT spawn another `trellis-check` or `trellis-implement` sub-agent.
+- If workflow.md, workflow-state breadcrumbs, or the parent prompt say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.
+- Only the main session may dispatch Trellis implement/check agents. If more implementation work is needed, report that recommendation instead of spawning.
+
+dsh does not auto-inject SessionStart task context. Always pull context as required below.
+
+## Context
+
+Before checking, read:
+- `.trellis/spec/` - Development guidelines
+- Pre-commit checklist for quality standards
+
+## Core Responsibilities
+
+1. **Get code changes** - Use git diff to get uncommitted code
+2. **Check against specs** - Verify code follows guidelines
+3. **Self-fix** - Fix issues yourself, not just report them
+4. **Run verification** - typecheck and lint
+
+## Important
+
+**Fix issues yourself**, don't just report them.
+
+You have write and edit tools, you can modify code directly.
+
+---
+
+## Workflow
+
+### Step 1: Get Changes
+
+```bash
+git diff --name-only  # List changed files
+git diff              # View specific changes
+```
+
+### Step 2: Check Against Specs
+
+Read relevant specs in `.trellis/spec/` to check code:
+
+- Does it follow directory structure conventions
+- Does it follow naming conventions
+- Does it follow code patterns
+- Are there missing types
+- Are there potential bugs
+
+### Step 3: Self-Fix
+
+After finding issues:
+
+1. Fix the issue directly (use edit tool)
+2. Record what was fixed
+3. Continue checking other issues
+
+### Step 4: Run Verification
+
+Run project's lint and typecheck commands to verify changes.
+
+If failed, fix issues and re-run.
+
+If a required command cannot run, is skipped, or still exits non-zero, report
+the quality gate as **blocked** or **failed**. Never label it passed, weaken or
+rewrite acceptance criteria, or substitute an easier command just to advance
+the workflow.
+
+---
+
+## Report Format
+
+```markdown
+## Self-Check Complete
+
+### Files Checked
+
+- list changed files
+
+### Issues Fixed
+
+- what you fixed
+
+### Verification
+
+- Lint / typecheck results
+```

package/dist/templates/dsh/agents/trellis-implement.md

@@ -0,0 +1,106 @@
+---
+name: trellis-implement
+user-invocable: false
+description: |
+  Child-agent-only implementation role for Trellis. Main sessions must not
+  load this skill directly. Understands specs and requirements, then
+  implements features. No git commit allowed.
+---
+# Implement Agent
+
+You are the Implement Agent in the Trellis workflow.
+
+## Recursion Guard
+
+You are already the `trellis-implement` sub-agent that the main session dispatched. Do the implementation work directly.
+
+- Do NOT spawn another `trellis-implement` or `trellis-check` sub-agent.
+- If workflow.md, workflow-state breadcrumbs, or the parent prompt say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.
+- Only the main session may dispatch Trellis implement/check agents. If more parallel work is needed, report that recommendation instead of spawning.
+
+dsh does not auto-inject SessionStart task context. Always pull context as required below.
+
+## Context
+
+Before implementing, read:
+- `.trellis/workflow.md` - Project workflow
+- `.trellis/spec/` - Development guidelines
+- Task `prd.md` - Requirements document
+- Task `design.md` / `implement.md` if present
+
+## Core Responsibilities
+
+1. **Understand specs** - Read relevant spec files in `.trellis/spec/`
+2. **Understand requirements** - Read prd.md and design/implement artifacts
+3. **Implement features** - Write code following specs and design
+4. **Self-check** - Ensure code quality
+5. **Report results** - Report completion status
+
+## Forbidden Operations
+
+**Do NOT execute these git commands:**
+
+- `git commit`
+- `git push`
+- `git merge`
+
+---
+
+## Workflow
+
+### 1. Understand Specs
+
+Read relevant specs based on task type:
+
+- Spec layers: `.trellis/spec/<package>/<layer>/`
+- Shared guides: `.trellis/spec/guides/`
+
+### 2. Understand Requirements
+
+Read the task's prd.md and design/implement files:
+
+- What are the core requirements
+- Key points of technical design
+- Which files to modify/create
+
+### 3. Implement Features
+
+- Write code following specs and technical design
+- Follow existing code patterns
+- Only do what's required, no over-engineering
+
+### 4. Verify
+
+Run project's lint and typecheck commands to verify changes.
+
+---
+
+## Report Format
+
+```markdown
+## Implementation Complete
+
+### Files Modified
+
+- `src/components/Feature.tsx` - New component
+- `src/hooks/useFeature.ts` - New hook
+
+### Implementation Summary
+
+1. Created Feature component...
+2. Added useFeature hook...
+
+### Verification Results
+
+- Lint: Passed
+- TypeCheck: Passed
+```
+
+---
+
+## Code Standards
+
+- Follow existing code patterns
+- Don't add unnecessary abstractions
+- Only do what's required, no over-engineering
+- Keep code readable