@mindfoldhq/trellis 0.5.0-beta.13 → 0.5.0-beta.14

package/dist/migrations/manifests/0.5.0-beta.14.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.5.0-beta.14",
+  "description": "Patch follow-up to beta.13: SessionStart hooks now emit a one-shot `<first-reply-notice>` block so the first visible assistant reply announces that Trellis context has been injected (proof-of-load for noisy or summarized hosts). READY-state breadcrumbs across shared/opencode/codex/copilot hooks + `trellis/workflow.md` replace the soft \"Continue with implement or check\" wording with an explicit \"Next required action: dispatch `trellis-implement` … do NOT edit code in the main session\" directive, closing a loophole where agent-capable sessions would still hand-edit code in the main thread. Windows statusline no longer crashes on typed stdout/stderr streams: `sys.stdout.detach() + TextIOWrapper(...)` is replaced with `reconfigure(encoding='utf-8', errors='replace')`. No src/ runtime-code changes outside templates; `trellis update` is a straight content refresh.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Enhancements:**\n- feat(hooks): SessionStart emits a one-shot `<first-reply-notice>` block instructing the model to open its first visible reply with one short Chinese sentence confirming Trellis context has been injected (workflow, task status, developer identity, git status, active tasks, spec index). Applied to `shared-hooks/session-start.py`, `codex/hooks/session-start.py`, `opencode/plugins/session-start.js`. Notice is explicitly one-shot — not repeated on later turns in the same session. Closes the visibility gap on hosts that collapse or summarize hook output.\n- feat(hooks): READY-state breadcrumbs now say \"Next required action: dispatch `trellis-implement` per Phase 2.1. For agent-capable platforms, do NOT edit code in the main session. After implementation, dispatch `trellis-check` per Phase 2.2 before reporting completion.\" Replaces the old \"Next: Continue with implement or check\" wording that let the main thread silently hand-edit code. Applied uniformly across `shared-hooks/session-start.py` + `inject-workflow-state.py`, `opencode/plugins/session-start.js` + `inject-workflow-state.js`, `codex/hooks/session-start.py`, `copilot/hooks/session-start.py`, and the `[workflow-state:in_progress]` block in `trellis/workflow.md`. `<ready>` directive also drops the \"ask whether to continue\" prompt in favor of \"execute its Next required action\".\n\n**Bug Fixes:**\n- fix(statusline): Windows UTF-8 setup replaces `sys.stdout = io.TextIOWrapper(sys.stdout.detach(), encoding='utf-8')` with `stream.reconfigure(encoding='utf-8', errors='replace')`. The old pattern crashed on hosts that wrap stdout/stderr with typed streams (Copilot / certain Codex environments) because `detach()` is not available on typed wrappers. `reconfigure` is the supported API on Python 3.7+ text streams and is a no-op when unavailable. Fix applied to `shared-hooks/statusline.py`.\n- fix(hooks): Codex and Copilot SessionStart hooks now invoke a shared `configure_project_encoding(project_dir)` helper before emitting JSON, loading `.trellis/scripts/common.configure_encoding()` when present. Prevents stray mojibake in hook stdout on Windows Codex/Copilot runs that haven't already wrapped stdout.\n- docs(copilot): `copilot/hooks/session-start.py` docstring + `systemMessage` text now state plainly that GitHub Copilot currently ignores `sessionStart` hook output. The JSON shape is kept for protocol parity and future host support, but users should rely on `UserPromptSubmit` breadcrumbs and hook logs for Copilot today.",
+  "migrations": [],
+  "notes": "Pure content refresh. Existing tasks, jsonl files, and `.current-task` are preserved. After `trellis update`, fresh sessions across Claude Code / Codex / Copilot / OpenCode will prepend a one-line Chinese confirmation of SessionStart context on the first assistant reply, and the main thread will no longer be nudged to hand-edit code when a task is READY. Windows statusline stops crashing on Copilot/Codex typed stdout. No action needed beyond `trellis update`."
+}

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

@@ -19,11 +19,31 @@ from pathlib import Path
 
 warnings.filterwarnings("ignore")
 
+FIRST_REPLY_NOTICE = """<first-reply-notice>
+On the first visible assistant reply in this session, begin with exactly one short Chinese sentence:
+Trellis SessionStart 已注入：workflow、当前任务状态、开发者身份、git 状态、active tasks、spec 索引已加载。
+Then continue directly with the user's request. This notice is one-shot: do not repeat it after the first assistant reply in the same session.
+</first-reply-notice>"""
+
 
 def should_skip_injection() -> bool:
     return os.environ.get("CODEX_NON_INTERACTIVE") == "1"
 
 
+def configure_project_encoding(project_dir: Path) -> None:
+    """Reuse Trellis' shared Windows stdio encoding helper before JSON output."""
+    scripts_dir = project_dir / ".trellis" / "scripts"
+    if str(scripts_dir) not in sys.path:
+        sys.path.insert(0, str(scripts_dir))
+
+    try:
+        from common import configure_encoding  # type: ignore[import-not-found]
+
+        configure_encoding()
+    except Exception:
+        pass
+
+
 def _has_curated_jsonl_entry(jsonl_path: Path) -> bool:
     """Return True iff jsonl has at least one row with a ``file`` field.
 
@@ -145,7 +165,12 @@ def _get_task_status(trellis_dir: Path) -> str:
     if not has_context:
         return f"Status: NOT READY\nTask: {task_title}\nMissing: implement.jsonl / check.jsonl missing or empty\nNext: Curate entries per workflow.md Phase 1.3 (spec + research files only), then `task.py start`"
 
-    return f"Status: READY\nTask: {task_title}\nNext: Continue with implement or check"
+    return (
+        f"Status: READY\nTask: {task_title}\n"
+        "Next required action: dispatch `trellis-implement` per Phase 2.1. "
+        "For agent-capable platforms, do NOT edit code in the main session. "
+        "After implementation, dispatch `trellis-check` per Phase 2.2 before reporting completion."
+    )
 
 
 def _extract_range(content: str, start_header: str, end_header: str) -> str:
@@ -203,6 +228,8 @@ def main() -> None:
     except (json.JSONDecodeError, KeyError):
         project_dir = Path(".").resolve()
 
+    configure_project_encoding(project_dir)
+
     trellis_dir = project_dir / ".trellis"
 
     output = StringIO()
@@ -213,6 +240,8 @@ Read and follow all instructions below carefully.
 </session-context>
 
 """)
+    output.write(FIRST_REPLY_NOTICE)
+    output.write("\n\n")
 
     output.write("<current-state>\n")
     context_script = trellis_dir / "scripts" / "get_context.py"
@@ -231,8 +260,9 @@ Read and follow all instructions below carefully.
         "- If you're spawning an implement/check sub-agent, context is injected "
         "automatically via `{task}/implement.jsonl` / `check.jsonl`. You do NOT "
         "need to read these indexes yourself.\n"
-        "- If you're editing code directly in the main session, Read the relevant "
-        "index(es) on-demand and follow their Pre-Dev Checklist.\n\n"
+        "- For agent-capable platforms, do NOT edit code directly in the main "
+        "session; dispatch `trellis-implement` and `trellis-check` so JSONL "
+        "context is loaded by the sub-agents.\n\n"
     )
 
     # guides/ inlined (cross-package thinking, broadly useful)
@@ -281,8 +311,8 @@ Read and follow all instructions below carefully.
 
     output.write("""<ready>
 Context loaded. Workflow index, project state, and guidelines are already injected above — do NOT re-read them.
-Wait for the user's first message, then handle it following the workflow guide.
-If there is an active task, ask whether to continue it.
+When the user sends the first message, follow <task-status> and the workflow guide.
+If a task is READY, execute its Next required action without asking whether to continue.
 </ready>""")
 
     context = output.getvalue()

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

@@ -1,10 +1,13 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 """
-Copilot Session Start Hook - Inject Trellis context into VS Code Copilot sessions.
+Copilot Session Start Hook - Emit Trellis session-start diagnostics.
 
-Output format follows Copilot hook protocol:
-  stdout JSON → { hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: "..." } }
+GitHub Copilot's documented SessionStart behavior ignores hook output, so this
+script must not be treated as proof that model-visible context was injected.
+The JSON shape is kept for parity with other Trellis hooks and future host
+support, but current Copilot users should rely on UserPromptSubmit breadcrumbs
+and hook logs instead.
 """
 
 from __future__ import annotations
@@ -24,6 +27,20 @@ def should_skip_injection() -> bool:
     return os.environ.get("COPILOT_NON_INTERACTIVE") == "1"
 
 
+def configure_project_encoding(project_dir: Path) -> None:
+    """Reuse Trellis' shared Windows stdio encoding helper before JSON output."""
+    scripts_dir = project_dir / ".trellis" / "scripts"
+    if str(scripts_dir) not in sys.path:
+        sys.path.insert(0, str(scripts_dir))
+
+    try:
+        from common import configure_encoding  # type: ignore[import-not-found]
+
+        configure_encoding()
+    except Exception:
+        pass
+
+
 def _has_curated_jsonl_entry(jsonl_path: Path) -> bool:
     """Return True iff jsonl has at least one row with a ``file`` field.
 
@@ -145,7 +162,12 @@ def _get_task_status(trellis_dir: Path) -> str:
     if not has_context:
         return f"Status: NOT READY\nTask: {task_title}\nMissing: implement.jsonl / check.jsonl missing or empty\nNext: Curate entries per workflow.md Phase 1.3 (spec + research files only), then `task.py start`"
 
-    return f"Status: READY\nTask: {task_title}\nNext: Continue with implement or check"
+    return (
+        f"Status: READY\nTask: {task_title}\n"
+        "Next required action: dispatch `trellis-implement` per Phase 2.1. "
+        "For agent-capable platforms, do NOT edit code in the main session. "
+        "After implementation, dispatch `trellis-check` per Phase 2.2 before reporting completion."
+    )
 
 
 def _extract_range(content: str, start_header: str, end_header: str) -> str:
@@ -203,6 +225,8 @@ def main() -> None:
     except (json.JSONDecodeError, KeyError):
         project_dir = Path(".").resolve()
 
+    configure_project_encoding(project_dir)
+
     trellis_dir = project_dir / ".trellis"
 
     output = StringIO()
@@ -231,8 +255,9 @@ Read and follow all instructions below carefully.
         "- If you're spawning an implement/check sub-agent, context is injected "
         "automatically via `{task}/implement.jsonl` / `check.jsonl`. You do NOT "
         "need to read these indexes yourself.\n"
-        "- If you're editing code directly in the main session, Read the relevant "
-        "index(es) on-demand and follow their Pre-Dev Checklist.\n\n"
+        "- For agent-capable platforms, do NOT edit code directly in the main "
+        "session; dispatch `trellis-implement` and `trellis-check` so JSONL "
+        "context is loaded by the sub-agents.\n\n"
     )
 
     # guides/ inlined (cross-package thinking, broadly useful)
@@ -281,14 +306,17 @@ Read and follow all instructions below carefully.
 
     output.write("""<ready>
 Context loaded. Workflow index, project state, and guidelines are already injected above — do NOT re-read them.
-Wait for the user's first message, then handle it following the workflow guide.
-If there is an active task, ask whether to continue it.
+When the user sends the first message, follow <task-status> and the workflow guide.
+If a task is READY, execute its Next required action without asking whether to continue.
 </ready>""")
 
     context = output.getvalue()
     result = {
         "suppressOutput": True,
-        "systemMessage": f"Trellis context injected ({len(context)} chars)",
+        "systemMessage": (
+            f"Trellis SessionStart diagnostics emitted ({len(context)} chars); "
+            "Copilot currently ignores sessionStart hook output."
+        ),
         "hookSpecificOutput": {
             "hookEventName": "SessionStart",
             "additionalContext": context,

package/dist/templates/opencode/plugins/inject-workflow-state.js

@@ -58,7 +58,11 @@ const FALLBACK_BREADCRUMBS = {
     "main session — PRD only links to research files.",
   in_progress:
     "Flow: trellis-implement → trellis-check → trellis-update-spec → finish\n" +
-    "Check conversation history + git status to determine current step; do NOT skip trellis-check.",
+    "Next required action: inspect conversation history + git status, then " +
+    "execute the next uncompleted step in that sequence.\n" +
+    "For agent-capable platforms, do NOT edit code in the main session; " +
+    "dispatch `trellis-implement` for implementation and dispatch " +
+    "`trellis-check` before reporting completion.",
   completed:
     "User commits changes; then run task.py archive.",
 }

package/dist/templates/opencode/plugins/session-start.js

@@ -14,6 +14,12 @@ import { TrellisContext, contextCollector, debugLog } from "../lib/trellis-conte
 
 const PYTHON_CMD = platform() === "win32" ? "python" : "python3"
 
+const FIRST_REPLY_NOTICE = `<first-reply-notice>
+On the first visible assistant reply in this session, begin with exactly one short Chinese sentence:
+Trellis SessionStart 已注入：workflow、当前任务状态、开发者身份、git 状态、active tasks、spec 索引已加载。
+Then continue directly with the user's request. This notice is one-shot: do not repeat it after the first assistant reply in the same session.
+</first-reply-notice>`
+
 
 /**
  * Return true iff jsonl has at least one row with a `file` field.
@@ -95,7 +101,12 @@ function getTaskStatus(ctx) {
     return `Status: NOT READY\nTask: ${taskTitle}\nMissing: implement.jsonl / check.jsonl missing or empty\nNext: Curate entries per workflow.md Phase 1.3 (spec + research files only), then \`task.py start\``
   }
 
-  return `Status: READY\nTask: ${taskTitle}\nNext: Continue with implement or check`
+  return (
+    `Status: READY\nTask: ${taskTitle}\n` +
+    "Next required action: dispatch `trellis-implement` per Phase 2.1. " +
+    "For agent-capable platforms, do NOT edit code in the main session. " +
+    "After implementation, dispatch `trellis-check` per Phase 2.2 before reporting completion."
+  )
 }
 
 /**
@@ -215,7 +226,7 @@ function resolveSpecScope(config) {
 /**
  * Build session context for injection
  */
-function buildSessionContext(ctx) {
+export function buildSessionContext(ctx) {
   const directory = ctx.directory
   const trellisDir = join(directory, ".trellis")
 
@@ -229,6 +240,7 @@ function buildSessionContext(ctx) {
 You are starting a new session in a Trellis-managed project.
 Read and follow all instructions below carefully.
 </trellis-context>`)
+  parts.push(FIRST_REPLY_NOTICE)
 
   // Legacy migration warning
   const legacyWarning = checkLegacySpec(directory, config)
@@ -288,8 +300,7 @@ Read and follow all instructions below carefully.
   }
 
   // 4. Guidelines — paths-only for most indexes; guides/ inlined (cross-package,
-  //    broadly useful). Sub-agents get their specific specs via jsonl injection —
-  //    main agent reads paths on demand when editing code directly.
+  //    broadly useful). Sub-agents get their specific specs via jsonl injection.
   parts.push("<guidelines>")
   parts.push(
     "Project spec indexes are listed by path below. Each index contains a " +
@@ -298,8 +309,9 @@ Read and follow all instructions below carefully.
     "- If you're spawning an implement/check sub-agent, context is injected " +
     "automatically via `{task}/implement.jsonl` / `check.jsonl`. You do NOT " +
     "need to read these indexes yourself.\n" +
-    "- If you're editing code directly in the main session, Read the relevant " +
-    "index(es) on-demand and follow their Pre-Dev Checklist.\n"
+    "- For agent-capable platforms, do NOT edit code directly in the main " +
+    "session; dispatch `trellis-implement` and `trellis-check` so JSONL " +
+    "context is loaded by the sub-agents.\n"
   )
 
   const specDir = join(directory, ".trellis", "spec")
@@ -379,8 +391,8 @@ Read and follow all instructions below carefully.
   // 7. Final directive
   parts.push(`<ready>
 Context loaded. Workflow index, project state, and guidelines are already injected above — do NOT re-read them.
-Wait for the user's first message, then handle it following the workflow guide.
-If there is an active task, ask whether to continue it.
+When the user sends the first message, follow <task-status> and the workflow guide.
+If a task is READY, execute its Next required action without asking whether to continue.
 </ready>`)
 
   return parts.join("\n\n")

package/dist/templates/shared-hooks/inject-workflow-state.py

@@ -153,8 +153,11 @@ _FALLBACK_BREADCRUMBS = {
     ),
     "in_progress": (
         "Flow: trellis-implement → trellis-check → trellis-update-spec → finish\n"
-        "Check conversation history + git status to determine current step; "
-        "do NOT skip trellis-check."
+        "Next required action: inspect conversation history + git status, then "
+        "execute the next uncompleted step in that sequence.\n"
+        "For agent-capable platforms, do NOT edit code in the main session; "
+        "dispatch `trellis-implement` for implementation and dispatch "
+        "`trellis-check` before reporting completion."
     ),
     "completed": (
         "User commits changes; then run task.py archive."

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

@@ -16,6 +16,12 @@ import sys
 from io import StringIO
 from pathlib import Path
 
+FIRST_REPLY_NOTICE = """<first-reply-notice>
+On the first visible assistant reply in this session, begin with exactly one short Chinese sentence:
+Trellis SessionStart 已注入：workflow、当前任务状态、开发者身份、git 状态、active tasks、spec 索引已加载。
+Then continue directly with the user's request. This notice is one-shot: do not repeat it after the first assistant reply in the same session.
+</first-reply-notice>"""
+
 # IMPORTANT: Force stdout to use UTF-8 on Windows
 # This fixes UnicodeEncodeError when outputting non-ASCII characters
 if sys.platform.startswith("win"):
@@ -209,10 +215,9 @@ def _get_task_status(trellis_dir: Path) -> str:
     # Case 5: PRD + curated jsonl (or agent-less platform with no jsonl) — enter Execute phase
     return (
         f"Status: READY\nTask: {task_title}\n"
-        "Next-Action: Follow Phase 2.1 for your platform. For agent-capable platforms, "
-        "spawn `trellis-implement` via the Task tool; if you stay in the main session, "
-        "load `trellis-before-dev` before writing code. "
-        "After implementation, spawn `trellis-check` sub-agent for quality verification.\n"
+        "Next required action: dispatch `trellis-implement` per Phase 2.1. "
+        "For agent-capable platforms, do NOT edit code in the main session. "
+        "After implementation, dispatch `trellis-check` per Phase 2.2 before reporting completion.\n"
         "Sub-agent roster: `trellis-implement` (writes code), `trellis-check` (verifies + self-fixes), "
         "`trellis-research` (persists findings to `research/*.md` — use when you'd otherwise do "
         "multiple WebFetch/WebSearch inline)."
@@ -469,6 +474,8 @@ Read and follow all instructions below carefully.
 </session-context>
 
 """)
+    output.write(FIRST_REPLY_NOTICE)
+    output.write("\n\n")
 
     # Legacy migration warning
     legacy_warning = _check_legacy_spec(trellis_dir, is_mono, packages)
@@ -492,8 +499,9 @@ Read and follow all instructions below carefully.
         "- If you're spawning an implement/check sub-agent, context is injected "
         "automatically via `{task}/implement.jsonl` / `check.jsonl`. You do NOT "
         "need to read these indexes yourself.\n"
-        "- If you're editing code directly in the main session, Read the relevant "
-        "index(es) on-demand and follow their Pre-Dev Checklist.\n\n"
+        "- For agent-capable platforms, do NOT edit code directly in the main "
+        "session; dispatch `trellis-implement` and `trellis-check` so JSONL "
+        "context is loaded by the sub-agents.\n\n"
     )
 
     # guides/ is cross-package thinking — always include inline (small, broadly useful)
@@ -550,8 +558,8 @@ Read and follow all instructions below carefully.
 
     output.write("""<ready>
 Context loaded. Workflow index, project state, and guidelines are already injected above — do NOT re-read them.
-Wait for the user's first message, then handle it following the workflow guide.
-If there is an active task, ask whether to continue it.
+When the user sends the first message, follow <task-status> and the workflow guide.
+If a task is READY, execute its Next required action without asking whether to continue.
 </ready>""")
 
     result = {

package/dist/templates/shared-hooks/statusline.py

@@ -11,7 +11,6 @@ Info line: model · ctx% · branch · duration · developer · tasks · rate lim
 """
 from __future__ import annotations
 
-import io
 import json
 import re
 import subprocess
@@ -21,8 +20,10 @@ from pathlib import Path
 # Fix: Windows Python defaults to GBK encoding, which corrupts UTF-8
 # characters like the middle dot (·). Wrap stdout/stderr with UTF-8.
 if sys.platform == "win32":
-    sys.stdout = io.TextIOWrapper(sys.stdout.detach(), encoding="utf-8")
-    sys.stderr = io.TextIOWrapper(sys.stderr.detach(), encoding="utf-8")
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if callable(reconfigure):
+            reconfigure(encoding="utf-8", errors="replace")
 
 
 def _read_text(path: Path) -> str:

package/dist/templates/trellis/workflow.md

@@ -471,7 +471,8 @@ Research belongs in `{task_dir}/research/*.md`, written by `trellis-research` su
 
 [workflow-state:in_progress]
 Flow: trellis-implement → trellis-check → trellis-update-spec → finish
-Check conversation history + git status to determine current step; do NOT skip trellis-check.
+Next required action: inspect conversation history + git status, then execute the next uncompleted step in that sequence.
+For agent-capable platforms, do NOT edit code in the main session; dispatch `trellis-implement` for implementation and dispatch `trellis-check` before reporting completion.
 [/workflow-state:in_progress]
 
 [workflow-state:completed]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindfoldhq/trellis",
-  "version": "0.5.0-beta.13",
+  "version": "0.5.0-beta.14",
   "description": "AI capabilities grow like ivy — Trellis provides the structure to guide them along a disciplined path",
   "type": "module",
   "main": "./dist/index.js",